Skip to main content

​
Before you start

Make sure you have the following:

​
Things to know

  • Accounts can be configured so that budget names must be unique per account. If set, and a budget with the same name already exists, you’ll receive an error.
  • Only one accountBalance budget can exist per account. This is created during onboarding and cannot be created via the API.
  • Only one individual budget can exist per persona. Attempting to create a second individual budget for the same persona will return an error.
  • Features must be enabled at account level first. You can only enable payments, peopleCards, or budgetCards on a budget if they are already enabled on the account. For example, if payments is not enabled on the account, you cannot enable it on the budget.
  • At least one currency is required. You must provide at least one currency when creating a budget.

​
Create a shared budget

POST /v2/budgets

​
Request

Use this request to create a new shared budget, which can be used by multiple people. 
curl -i -X POST \
  'https://api.equalsmoney.com/v2/budgets?accountId=F12345' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "parentId": "b489ea2c-0dd1-4fb1-b345-de5a596a5527",
    "name": "Team Party",
    "features": [
      "payments"
    ],
    "currencies": [
      "USD"
    ],
    "type": "shared",
    "status": "active"
  }'

​
Query parameters

​
accountId
string
required
The ID of the account that you’re creating a budget for.Allowable values: An existing accountId

​
Request body schema

​
parentId
string
required
The ID of the parent budget.Allowable values: An existing budgetId (≤ 36 characters)
​
name
string
required
The name of the new budget. Depending on your configuration, this might appear as the payee name.Allowable values: ≤ 75 characters
​
features
array of strings
required
The features that you want to enable for this budget.Allowable values: payments, peopleCards, budgetCards
​
currencies
array of strings
required
The currencies that you want to enable for this budget, in ISO 4217 format. You must provide at least one. If working with a sub-budget, the currencies you provide must be enabled on the parent budget.Allowable values: 3 characters
​
type
string
required
The type that you want this budget to be. Set this to shared. Learn more about budget types.Allowable values: shared, individual
​
status
string
The status of the budget.Allowable values: active, hidden
​
boxId
string
The ID of the box to work with.Allowable values: An existing boxId

​
Response

If your request is successful, you’ll receive a 201 response containing details about the newly-created sub-budget, including its id. 
{
  "createdAt": "2023-01-30T08:30:00Z",
  "updatedAt": "2023-01-30T08:30:00Z",
  "id": "b489ea2c-0dd1-4fb1-b345-de5a596a5527",
  "parentId": "b489ea2c-0dd1-4fb1-b345-de5a596a5527",
  "name": "Team Party",
  "type": "shared",
  "status": "active",
  "accountId": "F12345",
  "feature": [
    {
      "createdAt": "2023-01-30T08:30:00Z",
      "updatedAt": "2023-01-30T08:30:00Z",
      "budgetId": "b489ea2c-0dd1-4fb1-b345-de5a596a5527",
      "payments": true,
      "budgetCards": true,
      "peopleCards": true,
      "forwardDeposits": true,
      "BudgetId": "b489ea2c-0dd1-4fb1-b345-de5a596a5527"
    }
  ],
  "boxId": "f4a7d7c6-6124-45d9-9661-6240559fd1fe",
  "details": [
    {
      "currency": "USD",
      "sortCode": "12-34-56",
      "accountNumber": "12345678",
      "ibans": [
        {
          "iban": "GB26SPPV23188497371875",
          "bic": "BARCGB22"
        }
      ],
      "accountName": "Equals Money",
      "bankName": "SPECTRUM PAYMENT SERVICES",
      "bankAddress": "Vintners Place, 68 Upper Thames St, London, EC4V 3BJ, United Kingdom",
      "balanceReference": "Balance reference"
    }
  ]
}

​
Error responses

If your request is unsuccessful, you’ll receive one of the following error responses. 
{
  "path": "/v2/budgets",
  "message": "A budget with name: Team Party already exists"
}

{
  "path": "/v2/budgets",
  "message": "payments are not enabled for this account"
}

{
  "path": "/v2/budgets",
  "message": "cards are not enabled for this account"
}

{
  "path": "/v2/budgets",
  "message": "must have at least 1 active currency"
}

{
  "path": "/v2/budgets",
  "message": "Budgets count limit exceeded: 100"
}

{
  "path": "/v2/budgets",
  "message": "Account F12345 does not exist"
}
For more detailed information about this request and its response, see the API reference.

​
Create an individual budget

POST /v2/budgets

​
Request

Use this request to create an individual budget associated with a given personaId. The name of the budget will automatically be set to that persona’s {firstName} {lastName}. If the persona’s name is updated in the future, the budget’s name will also be updated.
A persona represents the relationship between a person and an account. To create an individual budget, you’ll need the personaId for the person you want to assign it to. You can find this by listing people on your account. Learn more about personas.
A single persona can only ever have one budget associated with them.
curl -i -X POST \
  'https://api.equalsmoney.com/v2/budgets?accountId=F12345' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "parentId": "b489ea2c-0dd1-4fb1-b345-de5a596a5527",
    "personaId": "42a27839-7690-486c-8cf4-5084fab52494",
    "features": [
      "payments"
    ],
    "currencies": [
      "USD"
    ],
    "type": "individual"
  }'

​
Query parameters

​
accountId
string
required
The ID of the account that you’re creating a budget for.Allowable values: An existing accountId

​
Request body schema

​
parentId
string
required
The ID of the parent budget.Allowable values: An existing budgetId (≤ 36 characters)
​
personaId
string
required
The ID of the persona that you’re creating this budget for.Allowable values: An existing personaId (≤ 36 characters)
​
features
array of strings
required
The features that you want to enable for this budget.Allowable values: payments, peopleCards, budgetCards
​
currencies
array of strings
required
The currencies that you want to enable for this budget, in ISO 4217 format. You must provide at least one. If working with a sub-budget, the currencies you provide must be enabled on the parent budget.Allowable values: 3 characters
​
type
string
required
The type that you want this budget to be. Set this to individual. Learn more about budget types.Allowable values: shared, individual
​
status
string
The status of the budget.Allowable values: active, hidden
​
boxId
string
The ID of the box to work with.Allowable values: An existing boxId

​
Response

If your request is successful, you’ll receive a 201 response containing details about the newly-created sub-budget, including its id. 
{
  "createdAt": "2023-01-30T08:30:00Z",
  "updatedAt": "2023-01-30T08:30:00Z",
  "id": "b489ea2c-0dd1-4fb1-b345-de5a596a5527",
  "parentId": "b489ea2c-0dd1-4fb1-b345-de5a596a5527",
  "name": "Jane Doe",
  "type": "individual",
  "status": "active",
  "accountId": "F12345",
  "feature": [
    {
      "createdAt": "2023-01-30T08:30:00Z",
      "updatedAt": "2023-01-30T08:30:00Z",
      "budgetId": "b489ea2c-0dd1-4fb1-b345-de5a596a5527",
      "payments": true,
      "budgetCards": true,
      "peopleCards": true,
      "forwardDeposits": true,
      "BudgetId": "b489ea2c-0dd1-4fb1-b345-de5a596a5527"
    }
  ],
  "boxId": "f4a7d7c6-6124-45d9-9661-6240559fd1fe",
  "details": [
    {
      "currency": "USD",
      "sortCode": "12-34-56",
      "accountNumber": "12345678",
      "ibans": [
        {
          "iban": "GB26SPPV23188497371875",
          "bic": "BARCGB22"
        }
      ],
      "accountName": "Equals Money",
      "bankName": "SPECTRUM PAYMENT SERVICES",
      "bankAddress": "Vintners Place, 68 Upper Thames St, London, EC4V 3BJ, United Kingdom",
      "balanceReference": "Balance reference"
    }
  ]
}

​
Error responses

If your request is unsuccessful, you’ll receive one of the following error responses. The shared budget error responses also apply to individual budgets, along with the following additional errors.
400 — Missing personaId
{
  "path": "/v2/budgets",
  "message": "personaId required to create Individual balance"
}
400 — Individual budget already exists for persona
{
  "path": "/v2/budgets",
  "message": "Individual budget already exists"
}
For more detailed information about this request and its response, see the API reference.