List all budgets
GET
/v2/budgetsRequest
Use this request to retrieve a list of budgets for a given account, based on itsid.
Query parameters
The ID of the account that you want to retrieve budgets for.Allowable values: An existing
accountIdThe 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 integerThe budget(s) to return. You can use this to filter results to specific budgets only.Allowable values: A comma-separated list of valid
budgetIdsOptional embeds to include in the results.Allowable values:
balance deprecated, budgetHierarchy, settlementDetailsThe 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 stringThe type of budget to filter results by.Allowable values:
accountBalance, shared, individualThe currency code to filter results by, in ISO-4217 format.Allowable values: 3 characters
Response
If your request is successful, you’ll receive a200 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.
Error responses
If your request is unsuccessful, you’ll receive one of the following error responses.400 — Missing accountId
Retrieve a budget’s details
GET
/v2/budgets/{budgetId}Request
Use this request to get details about a given budget, based on itsid.
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.Path parameters
The ID of the account that this budget belongs to.Allowable values: An existing
accountIdOptional embeds to include in the results.Allowable values:
children, balance deprecated, details deprecated, detailsActive, budgetHierarchy, settlementDetailsThe currency code to filter results by, in ISO-4217 format.Allowable values: 3 characters
Response
If your request is successful, you’ll receive a200 response containing details about the budget.
Error responses
If your request is unsuccessful, you’ll receive one of the following error responses.404 — Budget not found
Get settlement details
GET
/v2/budgets/{budgetId}/?accountId={accountId}&include=settlementDetailsRequest
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.Path parameters
The ID of the account that this budget belongs to.Allowable values: An existing
accountIdOptional 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, settlementDetailsThe currency code to filter results by, in ISO-4217 format.Allowable values: 3 characters
Response
If your request is successful, you’ll receive a200 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:
uniquemeans the settlement details returned are unique for your budgetsharedmeans that the settlement details are a pooled account that will need to be matched to your budget via a referenceanymeans 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.
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.