Finance · Accounting · Budgets
Get budget
Gets a budget by organization, mandate and budget ID, with an optional until month. Returns its planned lines, fiscal-year and comparison ranges, actuals for the comparison period and prior year, and monthly actuals for the full fiscal year. If until is omitted, the comparison runs through the end of the fiscal year.
Permissions
Send an API key of the organization in the path, using the X-API-Key header.
Who may call it
- The caller must have organization access.
- The caller needs
mandate.readandbudget.read.
Request
Path parameters
-
organizationIdidrequired -
mandateIdidrequired -
budgetIdidrequired
Body
Content-Type: application/json
-
untilobject2 properties
-
yearintegerrequired2000–3000
-
monthIndexintegerrequired1–12
-
curl --fail-with-body --silent --show-error --max-time 30 --globoff \
--request POST 'https://cloud.campai.com/api/YOUR_ORGANIZATION_ID/YOUR_MANDATE_ID/finance/accounting/budgets/YOUR_BUDGET_ID' \
--header 'X-API-Key: YOUR_API_KEY'const response = await fetch("https://cloud.campai.com/api/YOUR_ORGANIZATION_ID/YOUR_MANDATE_ID/finance/accounting/budgets/YOUR_BUDGET_ID", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY"
},
redirect: 'error',
signal: AbortSignal.timeout(30_000),
});
if (!response.ok) throw new Error(`campai HTTP ${response.status}`);
const text = await response.text();
const result = text ? JSON.parse(text) : null;
console.log(JSON.stringify(result, null, 2));<?php
$context = stream_context_create(['http' => [
'method' => 'POST',
'header' => [
'X-API-Key: YOUR_API_KEY',
],
'timeout' => 30,
'follow_location' => 0,
'ignore_errors' => true,
]]);
$text = @file_get_contents('https://cloud.campai.com/api/YOUR_ORGANIZATION_ID/YOUR_MANDATE_ID/finance/accounting/budgets/YOUR_BUDGET_ID', false, $context);
preg_match('/^HTTP\/\S+ (\d{3})/', $http_response_header[0] ?? '', $match);
$status = (int) ($match[1] ?? 0);
if ($text === false || $status < 200 || $status >= 300) {
throw new RuntimeException("campai HTTP $status (0 means no response)");
}
$result = $text === '' ? null : json_decode($text, true, 512, JSON_THROW_ON_ERROR);
echo json_encode($result, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR), PHP_EOL;
No request that worked has been recorded yet, so the body is not shown.
Response
200 Successful response
Content-Type: application/json
-
budgetobject7 properties
-
_idid -
mandateid -
fiscalYearinteger2000–3000
-
statusstringdraftapproved -
approvedAtstring · date-timenullable -
approvedByobjectnullableA non-contact
budget.approvedByactor other than the current actor is masked withoutuser.read.An API
budget.approvedByactor is masked withoutapiKey.read. If it is not the current actor,user.readis also needed. -
linesobject[]at most 20000 items
4 properties
-
accountinteger1–999999999
-
costCenternumbernullable1–99999999
-
amountinteger -
monthsinteger[]nullableexactly 12 items · each at most 9999999999
-
-
-
fiscalYearRangeobject2 properties
-
fromobject2 properties
-
yearinteger2000–3000
-
monthIndexinteger1–12
-
-
toobject2 properties
-
yearinteger2000–3000
-
monthIndexinteger1–12
-
-
-
rangeobject2 properties
-
fromobject2 properties
-
yearinteger2000–3000
-
monthIndexinteger1–12
-
-
toobject2 properties
-
yearinteger2000–3000
-
monthIndexinteger1–12
-
-
-
actualsobject[]4 properties
-
accountinteger1–999999999
-
costCenternumbernullable1–99999999
-
amountinteger -
previousAmountinteger
-
-
monthlyActualsobject[]4 properties
-
yearinteger -
monthIndexinteger1–12
-
revenueinteger -
expenseinteger
-
{
"budget": {
"_id": "000000000000000000000001",
"mandate": "000000000000000000000001",
"fiscalYear": 2000,
"status": "draft",
"approvedAt": "2026-06-15T22:30:00Z",
"approvedBy": {
"name": "string",
"type": "user",
"userId": "string",
"image": {
"resource": "string"
}
},
"lines": [
{
"account": 1,
"costCenter": 1,
"amount": 1,
"months": [
1
]
}
]
},
"fiscalYearRange": {
"from": {
"year": 2000,
"monthIndex": 1
},
"to": {
"year": 2000,
"monthIndex": 1
}
},
"range": {
"from": {
"year": 2000,
"monthIndex": 1
},
"to": {
"year": 2000,
"monthIndex": 1
}
},
"actuals": [
{
"account": 1,
"costCenter": 1,
"amount": 1,
"previousAmount": 1
}
],
"monthlyActuals": [
{
"year": 1,
"monthIndex": 1,
"revenue": 1,
"expense": 1
}
]
}
Errors
Other errors
| Status | Error | When |
|---|---|---|
| 400 | The month is not part of the fiscal year of the budget | If until is outside the budget's fiscal year, the response is 400 with routes.finance.accounting.budgets.untilOutsideFiscalYear. |
| 404 | Budget was not found | If the budget is not found, the response is 404 with routes.finance.accounting.budgets.notFound. |
| 404 | Accounting plan is missing. Please make sure you have setup your finances app properly. | If the accounting plan is missing, the response is 404 with finance.accounting.getAccountingPlan.notFound. |
| 404 | Finances settings are missing | If finances settings are missing, the response is 404 with finance.settings.getFinancesSettings.notFound. |
Errors nearly every request can meet are listed under Errors.