Projects

Projects are used to track and organize business activities, costs, and revenues. They serve as financial dimensions that can be assigned to journal entries, invoices, and other transactions to provide detailed project-based reporting and analysis.

Endpoints

Query Parameters

The GET /projects endpoint supports the following query parameters:

Attributes

Relationships

All relationships are opt-in and only included when requested via the with query parameter.

Statistics

Returned with with=statistics.

{
    "balances": [
        {"account_code": "3000", "balance": -15000.0},
        {"account_code": "6300", "balance": 4200.0}
    ],
    "last_used_at": "2026-10-14T09:30:00+00:00",
    "usage": {
        "item_collection_entries": {
            "count": 3,
            "amount": 2100.0,
            "used": 2,
            "used_amount": 1600.0,
            "unused": 1,
            "unused_amount": 500.0
        }
    }
}

Statistics are cached, and refreshed when a journal entry on the project is added or updated. usage can therefore lag behind recent changes to item collection entries.

Example Response

{
    "id": 1,
    "created_at": "2023-05-10T12:00:00Z",
    "created_by_id": 1,
    "updated_at": "2023-05-10T12:00:00Z",
    "updated_by_id": 1,
    "client_account_id": 1,
    "sequence_number": 1001,
    "name": "Website Redesign",
    "is_active": true,
    "autonomy_level": null
}

Deactivation Validation

When attempting to deactivate a project using the DELETE endpoint, the system performs validation to ensure data integrity:

• Balance Checking: The system checks if any accounting accounts with mandatory project dimensions have non-zero balances for this specific project.
• Validation Failure: If any accounts have non-zero balances, the deactivation is denied with a 400 Bad Request error.
• Error Details: The error message includes specific account codes and their balances to help identify which transactions need to be resolved.

Example Error Response

{
    "error": {
        "code": "common.validation_error",
        "message": "Cannot deactivate project: account 1500: 2500.00, account 2000: -750.00",
        "request_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
    }
}

This validation ensures that projects cannot be deactivated while they still have outstanding balances, maintaining the integrity of your accounting records.

Error Codes

Project endpoints use the common error codes. Errors raised by the project endpoints themselves include "details": {"resource": "project"}.

Example Error Response

{
    "error": {
        "code": "common.not_found",
        "message": "Project not found",
        "details": {"resource": "project"},
        "request_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
    }
}

Notes

• The client_account_id on individual project records must be one of the eligible client accounts for the authenticated user.
• When creating or updating a project, the created_by_id/updated_by_id is automatically set to the authenticated user’s ID.
• The sequence_number is automatically assigned when creating a new project.
• Project names must be unique within a client account.
• Both POST and PUT are accepted on /projects/{id} for updates — they behave identically.
• The DELETE endpoint deactivates the project (sets is_active to false) rather than permanently deleting the record.
• Projects with outstanding balances in mandatory dimension accounts cannot be deactivated until those balances are resolved.
• All dates are returned in ISO 8601 format.