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
| Method | Endpoint | Description |
|---|---|---|
| GET | /projects | List projects |
| POST | /projects | Create a project |
| GET | /projects/{id} | Get a project |
| PUT | /projects/{id} | Update a project |
| DELETE | /projects/{id} | Deactivate a project |
Query Parameters
The GET /projects endpoint supports the following query parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_account_id | integer | Yes | Filter by client account ID. Must be one of the user’s eligible client accounts |
| is_active | boolean | No | Filter by active status (default: true) |
| name | string | No | Search projects by name |
| page | integer | No | Page number for pagination (default: 1) |
| per_page | integer | No | Number of items per page (default: 50) |
Attributes
| Attribute | Type | Description |
|---|---|---|
| id | integer | The ID of the project |
| created_at | datetime | The date and time when the project was created |
| created_by_id | integer | The ID of the user that created the project |
| updated_at | datetime | The date and time when the project was last updated |
| updated_by_id | integer | The ID of the user that last updated the project |
| client_account_id | integer | The ID of the client account this project belongs to |
| sequence_number | integer | The sequence number of the project |
| name | string | The name of the project |
| description | string | A description of the project |
| is_active | boolean | Whether the project is active or not |
Relationships
| Relationship | Type | Description |
|---|---|---|
| client_account | ClientAccount | The client account of the project |
| journal_entries | JournalEntry | Journal entries associated with this project |
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",
"description": "Complete redesign of company website",
"is_active": true
}
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": "Cannot deactivate project: account 1500: 2500.00, account 2000: -750.00",
"status": 400
}
This validation ensures that projects cannot be deactivated while they still have outstanding balances, maintaining the integrity of your accounting records.
Notes
- The client_account_id 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.
- 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.