---
title: "Create a budget"
slug: "preview-create-a-budget"
updated: 2025-11-07T20:01:45Z
published: 2026-02-10T12:53:32Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://www.bloxs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a budget

Post/api/v1/finance/budgets

Create a new budget.

		
			

**Description**

This endpoint inserts (add) a budget. The 200 response contains a field named 'reference'. It is important to save this value since it is used as an identifier for all the other operations to recognise this specific entity

**Use Case**

The user wants to add a budget from outside the Bloxs application.

**Request****fields**

The request contains the following fields:

| Field | Description |
| --- | --- |
| externalIdentifier | The unique identifier for this specific budget, not created by Bloxs. |
| budgetType | Refers to the budget type: 1 = Operating Budget, 2 = Investment Budget. |
| ownerReference | The reference of the relation that owns the budget. This refers to the reference created by Bloxs, not to be confused with the externalIdentifier. |
| name | the name the user wants to assign to this budget. |
| calendarYear | The calendar year to which the budget applies. |
| ledgerAccountCode | The code of the ledger account. |
| realEstateObjectReference | This is the reference of the realestate object associated with the budget. This refers to the reference created by Bloxs, not to be confused with the externalIdentifier. |
| month | Indicates the month to which the budget applies. 1 = January, 2 = February, and so on. The 'Month' field is not required for Investment Budgets and only applies to Operating Budgets. |
| amount | The budgeted amount |

**Response fields**

In addition to the request, the 200 response contains the fields in the table below.

| Field | Description |
| --- | --- |
| reference | The unique identifier for this specific budget, created by Bloxs. |
| lastModified | Timestamp of the last modification within Bloxs (determined by Bloxs). |

		
		
SecurityHTTPType Bearer

Please enter a valid token

Body parameters<select class='api-response-data' aria-label='Media type'><option value='bfcc0405-29ce-428f-9c89-6c1c6f5739f5'>application/json</option>
</select>Expand Allobject  externalIdentifierstring   | null  Min length0Max length100
budgetTypeinteger  (int32)    RequiredValid values[
  1,
  2
]
ownerReferencestring    RequiredMin length0Max length100
namestring    RequiredMin length0Max length256
calendarYearinteger  (int32)    Required
lines Array of object (BudgetLine)   Requiredobject  ledgerAccountCodestring    RequiredMin length0Max length12
realEstateObjectReferencestring   | null  Min length0Max length100
monthinteger  (int32)    RequiredMinimum0Maximum12
amountnumber  (double)    Required

Responses200

The budget was created

<select class='api-response-data' aria-label='Media type'><option value='16665310-07bf-4d4f-89b5-0a26b984bd44'>application/json</option>
</select>Expand Allobject  referencestring   | null  Min length0Max length100
externalIdentifierstring   | null  Min length0Max length100
budgetTypeinteger  (int32)    Valid values[
  1,
  2
]
calendarYearinteger  (int32)    
ownerReferencestring    Min length0Max length100
lastModifiedstring  (date-time)    
lines Array of object (BudgetLine)  | null  object  ledgerAccountCodestring    Min length0Max length12
realEstateObjectReferencestring   | null  Min length0Max length100
monthinteger  (int32)    Minimum0Maximum12
amountnumber  (double)    

400

The budget data has validation issues

<select class='api-response-data' aria-label='Media type'><option value='c5c20407-b3db-4518-88e8-e76c820936ab'>application/json</option>
</select>Expand Allobject  typestring   | null  
titlestring   | null  
traceIdstring   | null  
statusinteger  (int32)    
errorsobject | null  property* Array of string  | null  additionalPropertiesstring