Projects
Project, subproject, and project profit endpoints
List all projects
Retrieves all projects for your company. By default archived projects are excluded.
Use ?includeArchived=true to also return archived (read-only) projects.
Required Scope
projects-read
Required License
- Projects — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
query Parameters
includeArchivedSet to true to include archived projects. Defaults to false.
List all projects › Responses
Project list returned successfully.
idUnique identifier of the project.
nameDisplay name of the project.
isArchivedWhether the project has been archived. Archived projects are read-only.
currencyISO 4217 currency code used for budget amounts on this project.
dimensionIdThe shared "Projects" dimension category ID (journal-tag category) that backs every project in your company. Subproject values live as dimension values under this category, nested beneath this project's own dimension value (dimensionValueId).
defaultSubprojectIdID of the default subproject (the catch-all subproject created with the project).
All subprojects for this project, sorted by sortOrder ascending.
createdAtISO 8601 timestamp when the project was created.
updatedAtISO 8601 timestamp when the project was last updated.
customerIdID of the customer this project belongs to. Null when not linked to a customer.
budgetHoursTotal budget in hours across all subprojects. Null when not set.
budgetAmountTotal budget amount in the project currency. Null when not set.
startDateProject start date (inclusive), ISO 8601 date string. Null when not set.
endDateProject end date (inclusive), ISO 8601 date string. Null when not set.
externalReferenceYour system external reference for this project. Useful for idempotent upserts and cross-system reconciliation. Null when not set.
colorHex colour code for visual identification. Null when not set.
dimensionValueIdThe project's own dimension value (journal-tag) ID inside the shared Projects category. Subprojects are nested as dimension values beneath this value. Null only for a project in a corrupt state with no journal-tag.
Create or update a project by external reference
Creates or updates a project identified by externalReference.
If no project with the given externalReference exists it is created and the response is 201 Created.
If a matching project already exists it is updated in place and the response is 200 OK.
Either way the response body is the project resource (same shape as create / get).
Concurrent requests with the same externalReference are safe: a unique-constraint race is caught and resolved to an update.
Required Scope
projects-write
Required License
- Projects — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
Error codes
PROJECT_NOT_FOUND— returned when the matched project is deleted mid-race (extremely rare).
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Create or update a project by external reference › Request Body
nameDisplay name for the project. Must be unique within your company.
customerIdID of the customer this project belongs to.
currencyISO 4217 currency code for budget amounts. Defaults to the customer's currency or the company base currency when omitted.
budgetHoursTotal budget in hours. Null clears the budget.
budgetAmountTotal budget amount in the project currency. Null clears the budget.
startDateProject start date (inclusive), ISO 8601 date string.
endDateProject end date (inclusive), ISO 8601 date string.
externalReferenceYour system external reference for this project. Must be unique within your company. The upsert finds an existing project by this value and updates it, or creates a new one.
colorHex colour code for visual identification.
Create or update a project by external reference › Responses
Existing project updated (matched by externalReference).
idUnique identifier of the project.
nameDisplay name of the project.
isArchivedWhether the project has been archived. Archived projects are read-only.
currencyISO 4217 currency code used for budget amounts on this project.
dimensionIdThe shared "Projects" dimension category ID (journal-tag category) that backs every project in your company. Subproject values live as dimension values under this category, nested beneath this project's own dimension value (dimensionValueId).
defaultSubprojectIdID of the default subproject (the catch-all subproject created with the project).
All subprojects for this project, sorted by sortOrder ascending.
createdAtISO 8601 timestamp when the project was created.
updatedAtISO 8601 timestamp when the project was last updated.
customerIdID of the customer this project belongs to. Null when not linked to a customer.
budgetHoursTotal budget in hours across all subprojects. Null when not set.
budgetAmountTotal budget amount in the project currency. Null when not set.
startDateProject start date (inclusive), ISO 8601 date string. Null when not set.
endDateProject end date (inclusive), ISO 8601 date string. Null when not set.
externalReferenceYour system external reference for this project. Useful for idempotent upserts and cross-system reconciliation. Null when not set.
colorHex colour code for visual identification. Null when not set.
dimensionValueIdThe project's own dimension value (journal-tag) ID inside the shared Projects category. Subprojects are nested as dimension values beneath this value. Null only for a project in a corrupt state with no journal-tag.
Create a project
Creates a new project. The project is automatically provisioned with a default (catch-all) subproject.
Required Scope
projects-write
Required License
- Projects — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
Error codes
PROJECT_EXTERNAL_REFERENCE_CONFLICT(409) — another project already has the sameexternalReference.
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Create a project › Request Body
nameDisplay name for the project. Must be unique within your company.
customerIdID of the customer this project belongs to.
currencyISO 4217 currency code for budget amounts. Defaults to the customer's currency or the company base currency when omitted.
budgetHoursTotal budget in hours. Null clears the budget.
budgetAmountTotal budget amount in the project currency. Null clears the budget.
startDateProject start date (inclusive), ISO 8601 date string.
endDateProject end date (inclusive), ISO 8601 date string.
externalReferenceYour system external reference for this project. Must be unique within your company. Can be used for idempotent upserts via PUT /.
colorHex colour code for visual identification.
Create a project › Responses
Project created successfully.
idUnique identifier of the project.
nameDisplay name of the project.
isArchivedWhether the project has been archived. Archived projects are read-only.
currencyISO 4217 currency code used for budget amounts on this project.
dimensionIdThe shared "Projects" dimension category ID (journal-tag category) that backs every project in your company. Subproject values live as dimension values under this category, nested beneath this project's own dimension value (dimensionValueId).
defaultSubprojectIdID of the default subproject (the catch-all subproject created with the project).
All subprojects for this project, sorted by sortOrder ascending.
createdAtISO 8601 timestamp when the project was created.
updatedAtISO 8601 timestamp when the project was last updated.
customerIdID of the customer this project belongs to. Null when not linked to a customer.
budgetHoursTotal budget in hours across all subprojects. Null when not set.
budgetAmountTotal budget amount in the project currency. Null when not set.
startDateProject start date (inclusive), ISO 8601 date string. Null when not set.
endDateProject end date (inclusive), ISO 8601 date string. Null when not set.
externalReferenceYour system external reference for this project. Useful for idempotent upserts and cross-system reconciliation. Null when not set.
colorHex colour code for visual identification. Null when not set.
dimensionValueIdThe project's own dimension value (journal-tag) ID inside the shared Projects category. Subprojects are nested as dimension values beneath this value. Null only for a project in a corrupt state with no journal-tag.
Get a project
Retrieves a single project by its ID, including all subprojects.
Required Scope
projects-read
Required License
- Projects — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
Error codes
PROJECT_NOT_FOUND(404) — no project with the given ID exists for your company.
path Parameters
idThe project UUID.
Get a project › Responses
Project returned successfully.
idUnique identifier of the project.
nameDisplay name of the project.
isArchivedWhether the project has been archived. Archived projects are read-only.
currencyISO 4217 currency code used for budget amounts on this project.
dimensionIdThe shared "Projects" dimension category ID (journal-tag category) that backs every project in your company. Subproject values live as dimension values under this category, nested beneath this project's own dimension value (dimensionValueId).
defaultSubprojectIdID of the default subproject (the catch-all subproject created with the project).
All subprojects for this project, sorted by sortOrder ascending.
createdAtISO 8601 timestamp when the project was created.
updatedAtISO 8601 timestamp when the project was last updated.
customerIdID of the customer this project belongs to. Null when not linked to a customer.
budgetHoursTotal budget in hours across all subprojects. Null when not set.
budgetAmountTotal budget amount in the project currency. Null when not set.
startDateProject start date (inclusive), ISO 8601 date string. Null when not set.
endDateProject end date (inclusive), ISO 8601 date string. Null when not set.
externalReferenceYour system external reference for this project. Useful for idempotent upserts and cross-system reconciliation. Null when not set.
colorHex colour code for visual identification. Null when not set.
dimensionValueIdThe project's own dimension value (journal-tag) ID inside the shared Projects category. Subprojects are nested as dimension values beneath this value. Null only for a project in a corrupt state with no journal-tag.
Update a project
Updates a project. All fields are optional — only provided fields are changed.
Send null for an optional field to clear it.
To archive a project set isArchived: true.
Required Scope
projects-write
Required License
- Projects — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
Error codes
PROJECT_NOT_FOUND(404) — no project with the given ID exists for your company.PROJECT_EXTERNAL_REFERENCE_CONFLICT(409) — another project already has the suppliedexternalReference.
path Parameters
idThe project UUID.
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Update a project › Request Body
nameNew display name for the project.
customerIdCustomer ID. Null clears the customer link.
currencyISO 4217 currency code.
budgetHoursBudget in hours. Null clears the budget.
budgetAmountBudget amount in the project currency. Null clears the budget.
startDateProject start date (inclusive), ISO 8601. Null clears the date.
endDateProject end date (inclusive), ISO 8601. Null clears the date.
externalReferenceExternal reference. Null clears the value.
colorHex colour code. Null clears the value.
isArchivedArchive or un-archive the project.
Update a project › Responses
Project updated successfully.
idUnique identifier of the project.
nameDisplay name of the project.
isArchivedWhether the project has been archived. Archived projects are read-only.
currencyISO 4217 currency code used for budget amounts on this project.
dimensionIdThe shared "Projects" dimension category ID (journal-tag category) that backs every project in your company. Subproject values live as dimension values under this category, nested beneath this project's own dimension value (dimensionValueId).
defaultSubprojectIdID of the default subproject (the catch-all subproject created with the project).
All subprojects for this project, sorted by sortOrder ascending.
createdAtISO 8601 timestamp when the project was created.
updatedAtISO 8601 timestamp when the project was last updated.
customerIdID of the customer this project belongs to. Null when not linked to a customer.
budgetHoursTotal budget in hours across all subprojects. Null when not set.
budgetAmountTotal budget amount in the project currency. Null when not set.
startDateProject start date (inclusive), ISO 8601 date string. Null when not set.
endDateProject end date (inclusive), ISO 8601 date string. Null when not set.
externalReferenceYour system external reference for this project. Useful for idempotent upserts and cross-system reconciliation. Null when not set.
colorHex colour code for visual identification. Null when not set.
dimensionValueIdThe project's own dimension value (journal-tag) ID inside the shared Projects category. Subprojects are nested as dimension values beneath this value. Null only for a project in a corrupt state with no journal-tag.
Get project profit
Returns aggregated profit/cost/revenue data for a project and its subprojects over a date range.
When from and to are omitted the current accounting year is used as the default range.
Required Scope
projects-read
Required License
- Projects — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
Error codes
PROJECT_NOT_FOUND(404) — no project with the given ID exists for your company.
path Parameters
idThe project UUID.
query Parameters
fromRange start (inclusive), YYYY-MM-DD.
toRange end (inclusive), YYYY-MM-DD.
Get project profit › Responses
Profit data returned successfully.
projectIdProject ID.
fromInclusive range start actually used (after defaulting), YYYY-MM-DD.
toInclusive range end actually used (after defaulting), YYYY-MM-DD.
currencyCompany base currency the amounts are expressed in.
Aggregate totals for the project.
Per-subproject profit breakdown.
Add a subproject
Creates a new subproject (dimension value) under the given project.
Required Scope
projects-write
Required License
- Projects — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
Error codes
PROJECT_NOT_FOUND(404) — the parent project does not exist.
path Parameters
idThe project UUID.
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Add a subproject › Request Body
nameDisplay name for the subproject.
budgetHoursBudget in hours for this subproject. Null clears the budget.
budgetAmountBudget amount in the project currency. Null clears the budget.
colorHex colour code. Null clears the value.
sortOrderSort order (ascending). Defaults to 0.
Add a subproject › Responses
Subproject created successfully.
idUnique identifier of the subproject.
dimensionValueIdThe journal-tag value ID that represents this subproject in the dimensions system. Use this value when tagging ledger transactions to the subproject.
nameDisplay name of the subproject.
isDefaultWhether this is the default (catch-all) subproject for the project.
sortOrderDisplay sort order (ascending).
budgetHoursBudget in hours for this subproject. Null when no budget is set.
budgetAmountBudget amount in the project currency for this subproject. Null when no budget is set.
colorHex colour code for visual identification in the UI. Null when not set.
Update a subproject
Updates an existing subproject. All fields are optional. Send null for an optional field to clear it.
Required Scope
projects-write
Required License
- Projects — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
Error codes
PROJECT_NOT_FOUND(404) — the parent project does not exist.SUBPROJECT_NOT_FOUND(404) — the subproject does not exist on this project.
path Parameters
idThe project UUID.
subprojectIdThe subproject UUID.
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Update a subproject › Request Body
nameNew display name for the subproject.
budgetHoursBudget in hours. Null clears the budget.
budgetAmountBudget amount in the project currency. Null clears the budget.
colorHex colour code. Null clears the value.
sortOrderSort order (ascending).
Update a subproject › Responses
Subproject updated successfully.
idUnique identifier of the subproject.
dimensionValueIdThe journal-tag value ID that represents this subproject in the dimensions system. Use this value when tagging ledger transactions to the subproject.
nameDisplay name of the subproject.
isDefaultWhether this is the default (catch-all) subproject for the project.
sortOrderDisplay sort order (ascending).
budgetHoursBudget in hours for this subproject. Null when no budget is set.
budgetAmountBudget amount in the project currency for this subproject. Null when no budget is set.
colorHex colour code for visual identification in the UI. Null when not set.
Delete a subproject
Deletes a subproject and its associated dimension value. The default (catch-all) subproject cannot be deleted.
Required Scope
projects-write
Required License
- Projects — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
Error codes
PROJECT_NOT_FOUND(404) — the parent project does not exist.SUBPROJECT_NOT_FOUND(404) — the subproject does not exist on this project.SUBPROJECT_IS_DEFAULT(400) — the subproject is the project's default catch-all and cannot be deleted.
path Parameters
idThe project UUID.
subprojectIdThe subproject UUID.
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Delete a subproject › Responses
Subproject deleted successfully.