Permanently delete an existing worked-time, estimated-time, or available-capacity record.
The record type and related objects are determined from the existing time record. The request only needs to specify its hour_id.
The {account_id} path parameter is the numeric identifier of the organization.
It must match the account associated with the supplied authentication credentials.
The endpoint supports:
GET — parameters are passed in the query stringPOST — parameters are passed in the request bodyBecause this method permanently deletes a record, POST is recommended.
POST https://api.doboard.com/42/hours_delete
Content-Type: application/json
{
"hour_id": 901,
"session_id": "abc123xyz"
}
Required
The request must contain valid authentication credentials associated with the account specified in the endpoint URL.
The current user must have access to the project associated with the time record.
This project-access requirement applies to administrators, project managers, and regular users.
A worked-time record with a non-zero hours_worked value can be deleted only by the user associated with that record.
Unlike hours_update, this method does not apply a five-day limit when deleting worked time.
An estimated-time record with a non-zero hours_estimated value can be deleted only by:
The administrator or project manager must also have access to the associated project.
An available-capacity record with a non-zero hours_avaible value can be deleted only by:
The administrator or project manager must also have access to the associated project.
An invalid session or token returns HTTP 401 Unauthorized.
A regular user attempting to delete a non-zero estimated-time or available-capacity record receives HTTP 403 Forbidden.
Some project and ownership access failures are returned as API error 2503 with HTTP status 200.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | Conditional | User session identifier. Required when another supported authentication mechanism is not used. |
token |
string | Conditional | API authentication token. |
project_token |
string | Conditional | Public project access token, where applicable. |
hour_id |
integer | Yes | Identifier of the time record to delete. |
No time value or related object identifier needs to be supplied.
The method determines the following values from the existing record:
Before deletion, the method verifies that:
hour_id was supplied.The request cannot change the record type or any relationship before deletion.
The selected database record is permanently removed.
This is a hard deletion:
hour_id cannot be used to retrieve, update, or delete the record again.If the record does not exist, the method returns error 2502.
| Stored record value | Required permission |
|---|---|
Non-zero hours_worked |
Current user must be the user associated with the record. |
Non-zero hours_estimated |
Current user must be an administrator or project manager. |
Non-zero hours_avaible |
Current user must be an administrator or project manager. |
Time value equal to 0 |
Only the common project-access check is applied. |
All deletion types require the current user to have access to the associated project.
Type-specific permission checks are based on whether the stored time value is non-zero. A record whose time value is
0is subject only to the project-access check.
A successful deletion returns the identifier of the deleted record.
{
"data": {
"operation_status": "SUCCESS",
"hour_id": 901
}
}
The deleted time record is not included in the HTTP response.
After successfully deleting the record, the method:
DELETE eventThe identifiers used for recalculation are taken from the record before it is deleted.
A successful deletion publishes an event with:
DELETEhoursThe WebSocket notification allows connected clients to remove the deleted record from their current state.
Validation and business-rule errors are generally returned with HTTP status 200 and operation_status: "FAILED".
| HTTP status | Description |
|---|---|
401 Unauthorized |
The session or token is missing or invalid. |
403 Forbidden |
A user without administrator or project manager permissions attempted to delete a non-zero estimated-time or available-capacity record. |
| Error number | Message | Description |
|---|---|---|
2501 |
hour_id is required |
The time record identifier was not supplied. |
2502 |
Hour Not Found |
No time record was found with the specified identifier. |
2503 |
Access is denied |
The current user does not have access to the associated project or attempted to delete another user's non-zero worked-time record. |
{
"data": {
"operation_status": "FAILED",
"operation_message": "Access is denied"
},
"error_message": "Access is denied",
"error_no": 2503
}
hour_id is required to identify the record.0 are subject only to the project-access check.hour_id but does not contain the deleted record object.hours_avaible.