> For the complete documentation index, see [llms.txt](https://docs.scaleconnect.com.au/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scaleconnect.com.au/api/rest-api/scaleapp-rest-api/actuals.md).

# Actuals

Recording and retrieving actual financial data (income, expenses)

## Create or update a personal financial actual

> Records a personal financial actual (income or expense) for the authenticated user.\
>     \
> \*\*Business Logic:\*\*\
> \- If an actual with the same date and type already exists, it will be updated\
> \- If the amount is 0 and an existing actual is found, it will be deleted\
> \- Supports both user's personal finances and strategy-specific finances via strategyId\
> \
> \*\*Use Cases:\*\*\
> \- Recording actual salary received\
> \- Tracking living expenses\
> \- Recording bonuses, side income, loan payments\
> \- Managing tax payments and HECS/HELP repayments\
> \
> \*\*For AI Agents:\*\*\
> \- Always include all three required fields: amount, date, and type\
> \- Date must be in ISO 8601 format (e.g., "2025-10-06T23:57:41.244Z")\
> \- Amount should be positive for income types and expenses (the system handles the direction)\
> \- Use strategyId when working with specific investment strategies rather than personal finances

```json
{"openapi":"3.0.0","info":{"title":"ScaleApp API","version":"1.0.0"},"tags":[{"name":"Actuals","description":"Recording and retrieving actual financial data (income, expenses)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"CreatePersonalActualDto":{"type":"object","properties":{"amount":{"type":"number","description":"The monetary amount for this personal financial actual entry. Can be income or expense depending on the type.","minimum":0},"date":{"type":"string","description":"The date when this personal financial actual occurred or will occur. Must be in ISO 8601 date-time format.","format":"date-time"},"type":{"type":"string","description":"The type of personal financial actual being recorded. This categorizes the income or expense entry.\n    \nAvailable types:\n- GROSS_ANUAL_SALARY: Annual gross salary before tax\n- LIVING_EXPENSES: Regular living costs (rent, food, utilities, etc.)\n- HECS_HELP_LOAN: Australian Higher Education Loan Program payments\n- DEPENDENTS: Costs related to dependents (children, family members)\n- SIDE_HUSTLE_INCOME: Income from secondary jobs or gigs\n- RECURRING_BONUSES: Regular bonuses (e.g., annual performance bonuses)\n- ONE_OFF_BONUSES: Non-recurring bonuses\n- PERSONAL_LOANS: Personal loan repayments\n- PAYG_TAX: Pay As You Go tax payments","enum":["GROSS_ANUAL_SALARY","LIVING_EXPENSES","HECS_HELP_LOAN","DEPENDENTS","SIDE_HUSTLE_INCOME","RECURRING_BONUSES","ONE_OFF_BONUSES","PERSONAL_LOANS","PAYG_TAX"]}},"required":["amount","date","type"]},"PersonalActualDeletedResponseDto":{"type":"object","properties":{"message":{"type":"string","description":"Message indicating the actual was deleted"}},"required":["message"]},"PersonalActualResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the personal actual entry"},"amount":{"type":"number","description":"The monetary amount for this personal financial actual entry. Can be income or expense depending on the type."},"date":{"type":"string","description":"The date when this personal financial actual occurred or will occur.","format":"date-time"},"endDate":{"type":"string","description":"The end date for recurring actuals. Null for one-time entries.","format":"date-time","nullable":true},"frequency":{"type":"string","description":"The frequency at which this financial actual occurs.\n    \nAvailable frequencies:\n- ONE_OFF: Single occurrence\n- WEEKLY: Occurs every week\n- FORTNIGHTLY: Occurs every two weeks  \n- MONTHLY: Occurs every month\n- QUARTERLY: Occurs every three months\n- ANNUALLY: Occurs every year","enum":["WEEKLY","MONTHLY","BI_MONTHLY","QUARTERLY","SEMI_ANUAL","ANNUAL","ONE_OFF"],"default":"ONE_OFF"},"type":{"type":"string","description":"The type of personal financial actual being recorded.\n    \nAvailable types:\n- GROSS_ANUAL_SALARY: Annual gross salary before tax\n- LIVING_EXPENSES: Regular living costs (rent, food, utilities, etc.)\n- HECS_HELP_LOAN: Australian Higher Education Loan Program payments\n- DEPENDENTS: Costs related to dependents (children, family members)\n- SIDE_HUSTLE_INCOME: Income from secondary jobs or gigs\n- RECURRING_BONUSES: Regular bonuses (e.g., annual performance bonuses)\n- ONE_OFF_BONUSES: Non-recurring bonuses\n- PERSONAL_LOANS: Personal loan repayments\n- PAYG_TAX: Pay As You Go tax payments","enum":["GROSS_ANUAL_SALARY","LIVING_EXPENSES","HECS_HELP_LOAN","DEPENDENTS","SIDE_HUSTLE_INCOME","RECURRING_BONUSES","ONE_OFF_BONUSES","PERSONAL_LOANS","PAYG_TAX"]},"createdAt":{"type":"string","description":"Timestamp when this entry was created","format":"date-time"},"updatedAt":{"type":"string","description":"Timestamp when this entry was last updated","format":"date-time"}},"required":["id","amount","date","frequency","type","createdAt","updatedAt"]}}},"paths":{"/v1/actual/personal":{"post":{"description":"Records a personal financial actual (income or expense) for the authenticated user.\n    \n**Business Logic:**\n- If an actual with the same date and type already exists, it will be updated\n- If the amount is 0 and an existing actual is found, it will be deleted\n- Supports both user's personal finances and strategy-specific finances via strategyId\n\n**Use Cases:**\n- Recording actual salary received\n- Tracking living expenses\n- Recording bonuses, side income, loan payments\n- Managing tax payments and HECS/HELP repayments\n\n**For AI Agents:**\n- Always include all three required fields: amount, date, and type\n- Date must be in ISO 8601 format (e.g., \"2025-10-06T23:57:41.244Z\")\n- Amount should be positive for income types and expenses (the system handles the direction)\n- Use strategyId when working with specific investment strategies rather than personal finances","operationId":"ActualController_createPersonal_v1","parameters":[{"name":"strategyId","required":false,"in":"query","description":"Optional. A control centre/strategy ID to associate this actual with a specific investment strategy. If not provided, associates with the user's personal finances.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePersonalActualDto"}}}},"responses":{"200":{"description":"Actual deleted because amount was 0","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonalActualDeletedResponseDto"}}}},"201":{"description":"Personal actual successfully created or updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonalActualResponseDto"}}}},"400":{"description":"Bad Request - Invalid input data (e.g., invalid date format, missing required fields)"},"401":{"description":"Unauthorized - Invalid or missing authentication token"}},"summary":"Create or update a personal financial actual","tags":["Actuals"]}}}}
```

## POST /v1/actual/property/{id}

>

```json
{"openapi":"3.0.0","info":{"title":"ScaleApp API","version":"1.0.0"},"tags":[{"name":"Actuals","description":"Recording and retrieving actual financial data (income, expenses)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"CreatePropertyActualDto":{"type":"object","properties":{"amount":{"type":"number"},"date":{"format":"date-time","type":"string"},"type":{"type":"string","enum":["CAPITAL_GROWTH","RENTAL_GROWTH","RENTAL_INCOME","OPERATING_COSTS","DEBT_PAYMENTS","COST_ESCALATION","VARIABLE_RATE"]}},"required":["amount","date","type"]}}},"paths":{"/v1/actual/property/{id}":{"post":{"operationId":"ActualController_createProperty_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePropertyActualDto"}}}},"responses":{"201":{"description":""}},"tags":["Actuals"]}}}}
```

## DELETE /v1/actual/property/{id}

>

```json
{"openapi":"3.0.0","info":{"title":"ScaleApp API","version":"1.0.0"},"tags":[{"name":"Actuals","description":"Recording and retrieving actual financial data (income, expenses)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}}},"paths":{"/v1/actual/property/{id}":{"delete":{"operationId":"ActualController_deletePpropertyActual_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Actuals"]}}}}
```

## Delete a personal financial actual

> Permanently deletes a personal financial actual entry by its ID.\
>     \
> \*\*Business Logic:\*\*\
> \- Removes the actual entry from the database\
> \- Cannot be undone - use caution\
> \- Can delete actuals from personal finances or strategy-specific finances\
> \
> \*\*Use Cases:\*\*\
> \- Removing incorrect entries\
> \- Cleaning up test data\
> \- Deleting outdated financial records\
> \
> \*\*For AI Agents:\*\*\
> \- Requires the actual's unique ID (UUID format)\
> \- Use strategyId if the actual belongs to a specific investment strategy\
> \- Confirm deletion intent before executing this operation

```json
{"openapi":"3.0.0","info":{"title":"ScaleApp API","version":"1.0.0"},"tags":[{"name":"Actuals","description":"Recording and retrieving actual financial data (income, expenses)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}}},"paths":{"/v1/actual/personal/{id}":{"delete":{"description":"Permanently deletes a personal financial actual entry by its ID.\n    \n**Business Logic:**\n- Removes the actual entry from the database\n- Cannot be undone - use caution\n- Can delete actuals from personal finances or strategy-specific finances\n\n**Use Cases:**\n- Removing incorrect entries\n- Cleaning up test data\n- Deleting outdated financial records\n\n**For AI Agents:**\n- Requires the actual's unique ID (UUID format)\n- Use strategyId if the actual belongs to a specific investment strategy\n- Confirm deletion intent before executing this operation","operationId":"ActualController_deletePersonalActual_v1","parameters":[{"name":"id","required":true,"in":"path","description":"Unique identifier (UUID) of the personal actual to delete","schema":{"type":"string"}},{"name":"strategyId","required":false,"in":"query","description":"Optional. A control centre/strategy ID if deleting from a specific investment strategy.","schema":{"type":"string"}}],"responses":{"200":{"description":"Personal actual successfully deleted"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"404":{"description":"Not Found - Actual with the specified ID does not exist"}},"summary":"Delete a personal financial actual","tags":["Actuals"]}}}}
```

## Get personal financial totals for a specific financial year

> Retrieves aggregated totals for all personal financial categories for a given financial year.\
>     \
> \*\*Business Logic:\*\*\
> \- Financial year runs from July 1 to June 30 (Australian financial year)\
> \- Aggregates all income and expense categories\
> \- Includes both actual recorded values and projected values\
> \- Returns totals for: salary, expenses, loans, bonuses, taxes, etc.\
> \
> \*\*Use Cases:\*\*\
> \- Annual financial review\
> \- Tax preparation\
> \- Financial planning and budgeting\
> \- Year-over-year comparisons\
> \
> \*\*For AI Agents:\*\*\
> \- Year parameter should be a 4-digit year (e.g., "2025")\
> \- Returns data for the financial year ending in the specified year (e.g., 2025 = July 2024 to June 2025)\
> \- Use strategyId when analyzing strategy-specific finances\
> \- Response includes totals for all personal financial categories

```json
{"openapi":"3.0.0","info":{"title":"ScaleApp API","version":"1.0.0"},"tags":[{"name":"Actuals","description":"Recording and retrieving actual financial data (income, expenses)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"PersonalYearTotalResponseDto":{"type":"object","properties":{"fromDate":{"type":"string","description":"The start date of the financial year period","format":"date"},"toDate":{"type":"string","description":"The end date of the financial year period","format":"date"},"totals":{"description":"Array of total amounts for each personal financial category","type":"array","items":{"$ref":"#/components/schemas/PersonalTotalDto"}}},"required":["fromDate","toDate","totals"]},"PersonalTotalDto":{"type":"object","properties":{"actualType":{"type":"string","description":"The type of personal financial category","enum":["GROSS_ANUAL_SALARY","LIVING_EXPENSES","HECS_HELP_LOAN","DEPENDENTS","SIDE_HUSTLE_INCOME","RECURRING_BONUSES","ONE_OFF_BONUSES","PERSONAL_LOANS","PAYG_TAX"]},"label":{"type":"string","description":"Human-readable label for this financial category"},"amount":{"type":"number","description":"The total amount for this category across the year"}},"required":["actualType","label","amount"]}}},"paths":{"/v1/actual/personal-total/{year}":{"get":{"description":"Retrieves aggregated totals for all personal financial categories for a given financial year.\n    \n**Business Logic:**\n- Financial year runs from July 1 to June 30 (Australian financial year)\n- Aggregates all income and expense categories\n- Includes both actual recorded values and projected values\n- Returns totals for: salary, expenses, loans, bonuses, taxes, etc.\n\n**Use Cases:**\n- Annual financial review\n- Tax preparation\n- Financial planning and budgeting\n- Year-over-year comparisons\n\n**For AI Agents:**\n- Year parameter should be a 4-digit year (e.g., \"2025\")\n- Returns data for the financial year ending in the specified year (e.g., 2025 = July 2024 to June 2025)\n- Use strategyId when analyzing strategy-specific finances\n- Response includes totals for all personal financial categories","operationId":"ActualController_getPersonalTotalYear_v1","parameters":[{"name":"year","required":true,"in":"path","description":"The financial year (4-digit format). Returns data from July of previous year to June of specified year.","schema":{"type":"string"}},{"name":"strategyId","required":false,"in":"query","description":"Optional. A control centre/strategy ID to get totals for a specific investment strategy.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved personal financial totals for the year","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonalYearTotalResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"}},"summary":"Get personal financial totals for a specific financial year","tags":["Actuals"]}}}}
```

## Get personal financial data for a specific category and year

> Retrieves detailed monthly breakdown for a specific personal financial category in a given financial year.\
>     \
> \*\*Business Logic:\*\*\
> \- Financial year runs from July 1 to June 30 (Australian financial year)\
> \- Returns month-by-month breakdown showing actual vs projected values\
> \- Includes total for the year for the specified category\
> \- Each month indicates whether it's an actual recorded value or a projection\
> \
> \*\*Use Cases:\*\*\
> \- Detailed category analysis (e.g., tracking monthly salary payments)\
> \- Identifying months with actual data vs projections\
> \- Monthly cash flow analysis for specific categories\
> \- Comparing planned vs actual expenses/income\
> \
> \*\*For AI Agents:\*\*\
> \- Type parameter must match PersonalQuickActionType enum values\
> \- Year should be 4-digit format (e.g., "2025")\
> \- Response includes 12 months of data (July to June)\
> \- Use isActual field to distinguish recorded data from projections\
> \- Useful for drilling down into specific financial categories

```json
{"openapi":"3.0.0","info":{"title":"ScaleApp API","version":"1.0.0"},"tags":[{"name":"Actuals","description":"Recording and retrieving actual financial data (income, expenses)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"PersonalYearTypeResponseDto":{"type":"object","properties":{"actualType":{"type":"string","description":"The type of personal financial category being queried","enum":["GROSS_ANUAL_SALARY","LIVING_EXPENSES","HECS_HELP_LOAN","DEPENDENTS","SIDE_HUSTLE_INCOME","RECURRING_BONUSES","ONE_OFF_BONUSES","PERSONAL_LOANS","PAYG_TAX"]},"fromDate":{"type":"string","description":"The start date of the financial year period","format":"date"},"toDate":{"type":"string","description":"The end date of the financial year period","format":"date"},"total":{"type":"number","description":"The total amount for this category across the entire year"},"months":{"description":"Monthly breakdown of amounts, showing actual vs projected values","type":"array","items":{"$ref":"#/components/schemas/MonthlyActualDto"}}},"required":["actualType","fromDate","toDate","total","months"]},"MonthlyActualDto":{"type":"object","properties":{"isActual":{"type":"boolean","description":"Indicates whether this is an actual recorded value (true) or a projected/estimated value (false)"},"date":{"type":"string","description":"The date for this monthly entry in ISO format","format":"date"},"amount":{"type":"number","description":"The monetary amount for this month"}},"required":["isActual","date","amount"]}}},"paths":{"/v1/actual/personal/{type}/{year}":{"get":{"description":"Retrieves detailed monthly breakdown for a specific personal financial category in a given financial year.\n    \n**Business Logic:**\n- Financial year runs from July 1 to June 30 (Australian financial year)\n- Returns month-by-month breakdown showing actual vs projected values\n- Includes total for the year for the specified category\n- Each month indicates whether it's an actual recorded value or a projection\n\n**Use Cases:**\n- Detailed category analysis (e.g., tracking monthly salary payments)\n- Identifying months with actual data vs projections\n- Monthly cash flow analysis for specific categories\n- Comparing planned vs actual expenses/income\n\n**For AI Agents:**\n- Type parameter must match PersonalQuickActionType enum values\n- Year should be 4-digit format (e.g., \"2025\")\n- Response includes 12 months of data (July to June)\n- Use isActual field to distinguish recorded data from projections\n- Useful for drilling down into specific financial categories","operationId":"ActualController_getPersonalYear_v1","parameters":[{"name":"type","required":true,"in":"path","description":"The type of personal financial category to retrieve","schema":{"enum":["GROSS_ANUAL_SALARY","LIVING_EXPENSES","HECS_HELP_LOAN","DEPENDENTS","SIDE_HUSTLE_INCOME","RECURRING_BONUSES","PERSONAL_LOANS","PAYG_TAX","MISC_INVESTMENT_CASHFLOWS"],"type":"string"}},{"name":"year","required":true,"in":"path","description":"The financial year (4-digit format)","schema":{"type":"string"}},{"name":"strategyId","required":false,"in":"query","description":"Optional. A control centre/strategy ID for strategy-specific analysis.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved monthly breakdown for the specified category","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonalYearTypeResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"}},"summary":"Get personal financial data for a specific category and year","tags":["Actuals"]}}}}
```

## GET /v1/actual/property-total/{id}/{year}

>

```json
{"openapi":"3.0.0","info":{"title":"ScaleApp API","version":"1.0.0"},"tags":[{"name":"Actuals","description":"Recording and retrieving actual financial data (income, expenses)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"PropertyYearTotalDto":{"type":"object","properties":{"fromDate":{"type":"string","description":"The start date of the financial year period","format":"date"},"toDate":{"type":"string","description":"The end date of the financial year period","format":"date"},"totals":{"description":"The total amount for this category across the year","type":"array","items":{"$ref":"#/components/schemas/PropertyYearTotalItemDto"}}},"required":["fromDate","toDate","totals"]},"PropertyYearTotalItemDto":{"type":"object","properties":{"actualType":{"type":"string","description":"The type of property financial category"},"label":{"type":"string","description":"The label of the property financial category"},"amount":{"type":"number","description":"The amount of the property financial category"}},"required":["label","amount"]}}},"paths":{"/v1/actual/property-total/{id}/{year}":{"get":{"operationId":"ActualController_getPropertyTotalYear_v1","parameters":[{"name":"id","required":true,"in":"path","description":"The ID of the property to retrieve totals for","schema":{"type":"string"}},{"name":"year","required":true,"in":"path","description":"The financial year (4-digit format). Returns data from July of previous year to June of specified year.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved property financial totals for the year","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyYearTotalDto"}}}}},"tags":["Actuals"]}}}}
```

## GET /v1/actual/property/{id}/{type}/{year}

>

```json
{"openapi":"3.0.0","info":{"title":"ScaleApp API","version":"1.0.0"},"tags":[{"name":"Actuals","description":"Recording and retrieving actual financial data (income, expenses)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}}},"paths":{"/v1/actual/property/{id}/{type}/{year}":{"get":{"operationId":"ActualController_getPropertyYear_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"type","required":true,"in":"path","schema":{"type":"string"}},{"name":"year","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Actuals"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.scaleconnect.com.au/api/rest-api/scaleapp-rest-api/actuals.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.