> ## 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 > Create a new budget. ## OpenAPI ````json POST /api/v1/finance/budgets { "openapi": "3.0.4", "info": { "title": "Invoices V1", "description": "Welcome to BETA version of the new Invoices API - intended for client public testing before the launch of the final version. During this BETA phase, we'll be improving the API based on specific client's feedbacks.", "version": "v1" }, "security": [ {} ], "tags": [ { "name": "Budgets" }, { "name": "Compactions" }, { "name": "ConceptPurchaseInvoices" }, { "name": "JournalPosts" }, { "name": "Journals" }, { "name": "LedgerAccounts" }, { "name": "Metadata" }, { "name": "PaymentReminders" }, { "name": "PurchaseInvoices" }, { "name": "PurchaseOrders" }, { "name": "SalesInvoices" }, { "name": "SalesInvoiceServices" } ], "paths": { "/api/v1/finance/budgets": { "post": { "tags": [ "Budgets" ], "summary": "Create a budget", "description": "Create a new budget.", "operationId": "CreateBudget", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Budget" } } } }, "responses": { "200": { "description": "The budget was created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetDetail" } } } }, "400": { "description": "The budget data has validation issues", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorMessageModel" } } } } }, "x-d360-narrative-url": "

Create a Budget

Creates a new budget in Bloxs.

A developer calls this endpoint to register a budget for a specific owner's financial administration and calendar year, broken down into lines per ledger account (and optionally per real estate object) and period.

Multiple budgets can exist for the same owner, budget type, and calendar year combination; no uniqueness constraint applies.

On success, Bloxs generates and returns the internal reference for the new record, along with the full stored data.

Request Fields

Field

Type

Required

Description

budgetType

integer (enum)

Required

The type of budget. Allowed values: 1 = OperatingBudget, 2 = InvestmentBudget.

ownerReference

string, max 100

Required

The internal identifier (Reference/Code) of the owner whose financial administration this budget belongs to.

name

string, max 256

Required

The name of the budget. Stored on creation but not returned by Get a Budget.

calendarYear

integer

Required

The calendar year this budget applies to, for example 2026.

externalIdentifier

string, max 100, nullable

Optional

An external API identifier to associate with this budget, if the integrating system wants to track its own identifier for the record.

lines

array of objects

Required

The budget's line items. See sub-fields below.

lines.ledgerAccountCode

string, max 12

Required (within each line)

The general ledger account code this budget line applies to. Enforced: omitting this on a line returns a validation error.

lines.realEstateObjectReference

string, max 100, nullable

Optional

The internal identifier of the real estate object this budget line is allocated to, if the budget is broken down at the object level rather than only at the owner level. Must belong to a real estate object owned by the same ownerReference as the budget.

lines.month

integer, 0 to 12

Required (within each line)

The period this budget line applies to. Values 1 through 12 correspond to calendar months. 0 represents period 0, typically used for the starting balance of the financial year. Since 0 is also the default value when this field is omitted, omitting it is indistinguishable from explicitly setting it to period 0.

lines.amount

number (double)

Required (within each line)

The budgeted amount for this line, in the administration's base currency (major units, for example euros with decimals). The sign follows debit/credit convention relative to the ledger account referenced by ledgerAccountCode. Since 0 is also the default value when this field is omitted, omitting it is indistinguishable from explicitly setting it to zero.

Response Fields

Field

Type

Required

Description

reference

string, max 100, nullable

Optional

The internal identifier (Reference/Code) generated by Bloxs for the newly created budget.

externalIdentifier

string, max 100, nullable

Optional

The external API identifier for this budget, if one was supplied on creation.

budgetType

integer (enum), nullable

Optional

The type of budget. Allowed values: 1 = OperatingBudget, 2 = InvestmentBudget.

calendarYear

integer

Optional

The calendar year this budget applies to.

ownerReference

string, max 100

Required

The internal identifier (Reference/Code) of the owner whose financial administration this budget belongs to.

lastModified

string (date-time)

Optional

The date and time the budget was created, formatted as ISO 8601.

lines

array of objects, nullable

Optional

The budget's line items as stored. See sub-fields below.

lines.ledgerAccountCode

string, max 12

Required (within each line)

The general ledger account code this budget line applies to.

lines.realEstateObjectReference

string, max 100, nullable

Optional

The internal identifier of the real estate object this budget line is allocated to, if applicable.

lines.month

integer, 0 to 12

Required (within each line)

The period this budget line applies to.

lines.amount

number (double)

Required (within each line)

The budgeted amount for this line.

" } } }, "components": { "schemas": { "Budget": { "required": [ "budgetType", "calendarYear", "lines", "name", "ownerReference" ], "type": "object", "properties": { "externalIdentifier": { "maxLength": 100, "minLength": 0, "type": "string", "nullable": true }, "budgetType": { "type": "integer", "description": "OperatingBudget = 1\nInvestmentBudget = 2", "format": "int32", "x-enumNames": [ "OperatingBudget", "InvestmentBudget" ] }, "ownerReference": { "maxLength": 100, "minLength": 0, "type": "string" }, "name": { "maxLength": 256, "minLength": 0, "type": "string" }, "calendarYear": { "type": "integer", "format": "int32" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/BudgetLine" } } }, "additionalProperties": false }, "BudgetDetail": { "required": [ "ownerReference" ], "type": "object", "properties": { "reference": { "maxLength": 100, "minLength": 0, "type": "string", "nullable": true }, "externalIdentifier": { "maxLength": 100, "minLength": 0, "type": "string", "nullable": true }, "budgetType": { "type": "integer", "description": "OperatingBudget = 1\nInvestmentBudget = 2", "format": "int32", "x-enumNames": [ "OperatingBudget", "InvestmentBudget" ] }, "calendarYear": { "type": "integer", "format": "int32" }, "ownerReference": { "maxLength": 100, "minLength": 0, "type": "string" }, "lastModified": { "type": "string", "format": "date-time" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/BudgetLine" }, "nullable": true } }, "additionalProperties": false }, "APIErrorMessageModel": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "traceId": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" }, "nullable": true }, "nullable": true } }, "additionalProperties": false }, "BudgetLine": { "required": [ "amount", "ledgerAccountCode", "month" ], "type": "object", "properties": { "ledgerAccountCode": { "maxLength": 12, "minLength": 0, "type": "string" }, "realEstateObjectReference": { "maxLength": 100, "minLength": 0, "type": "string", "nullable": true }, "month": { "maximum": 12, "minimum": 0, "type": "integer", "format": "int32" }, "amount": { "type": "number", "format": "double" } }, "additionalProperties": false } } } } ````