Create a worked-time, estimated-time, or available-capacity record.
The method supports three record types:
Only one time value is stored in each record.
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 creates a new record, POST is recommended.
POST https://api.doboard.com/42/hours_add
Content-Type: application/json
{
"comment_id": 501,
"hours_worked": 7200,
"session_id": "abc123xyz"
}
POST https://api.doboard.com/42/hours_add
Content-Type: application/json
{
"task_id": 101,
"user_id": 5,
"hours_estimated": 14400,
"session_id": "abc123xyz"
}
POST https://api.doboard.com/42/hours_add
Content-Type: application/json
{
"track_id": 12,
"user_id": 5,
"hours_avaible": 28800,
"session_id": "abc123xyz"
}
Time values are specified in seconds. For example,
7200represents 2 hours.
Required
The request must contain valid authentication credentials associated with the account specified in the endpoint URL.
Supported authentication contexts include:
Authorization depends on the type of time record being created.
An authenticated user can add worked time only to their own active comment.
The comment must be associated with a task.
Estimated time can be added only by:
A project manager must have access to the project containing the task.
If user_id identifies an existing user, that user must also belong to the task's project.
Available capacity can be added only by:
A project manager must have access to the project containing the track.
The target user must exist and belong to the track's project.
An invalid session or token returns HTTP 401 Unauthorized. Insufficient permissions return HTTP 403 Forbidden.
| 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. |
hours_worked |
integer | Conditional | Worked time in seconds. Requires comment_id. |
hours_estimated |
integer | Conditional | Estimated time in seconds. Requires task_id. |
hours_avaible |
integer | Conditional | Available capacity in seconds. Requires track_id and user_id. |
comment_id |
integer | Conditional | Active comment to which worked time is attached. |
task_id |
integer | Conditional | Task for which estimated time is added. |
track_id |
integer | Conditional | Track for which available capacity is added. |
user_id |
integer | Conditional | Target user for estimated time or available capacity. |
At least one of the following parameters must be provided:
hours_workedhours_estimatedhours_avaibleEach time value is converted to an integer and must not exceed 4294967295.
A numeric value of 0 is treated as not provided.
The parameter name
hours_avaibleintentionally uses this spelling and must be sent exactly as shown.
If more than one time value is supplied, the method processes only the first non-empty value in this order:
hours_workedhours_estimatedhours_avaibleThe remaining time fields are stored as null.
Applications should provide only one time value per request.
To add worked time, provide:
hours_workedcomment_idThe selected comment must:
ACTIVE statusThe task, track, and project identifiers are determined from the comment and its task.
The worked-time record receives:
user_idcomment_idsubmittedupdatedOnly one worked-time record can exist for the same comment.
To add estimated time, provide:
hours_estimatedtask_idThe task must exist.
The related track and project identifiers are determined from the task.
The optional user_id parameter identifies the user associated with the estimate:
user_id is omitted.The record receives the current time for both submitted and updated.
Only one estimated-time record can exist for the same task and track combination.
To add available capacity, provide:
hours_avaibletrack_iduser_idThe track must exist and must be associated with a project.
The target user must:
The record is associated with the specified user, track, and project. It is not associated with a task or comment.
The record receives the current time for both submitted and updated.
Only one available-capacity record can exist for the same user and track combination.
| Record type | Duplicate condition |
|---|---|
| Worked time | A worked-time record already exists for the same comment_id. |
| Estimated time | An estimated-time record already exists for the same task_id and track. |
| Available capacity | An available-capacity record already exists for the same user_id and track_id. |
Known duplicates are rejected instead of creating an additional time record.
A successful request returns the created record identifier and an array containing the resulting time record.
{
"data": {
"operation_status": "SUCCESS",
"hour_id": 901,
"hours": [
{
"hour_id": 901,
"user_id": 5,
"comment_id": 501,
"task_id": 101,
"track_id": 12,
"project_id": 7,
"submitted": "2026-09-18 09:30:00",
"updated": "2026-09-18 10:15:00",
"hours_estimated": null,
"hours_worked": 7200,
"hours_avaible": null
}
]
}
}
| Field | Type | Description |
|---|---|---|
hour_id |
integer | Unique identifier of the time record. |
user_id |
integer or null | User associated with the record. |
comment_id |
integer or null | Comment associated with worked time. |
task_id |
integer or null | Related task identifier. |
track_id |
integer or null | Related track identifier. |
project_id |
integer or null | Related project identifier. |
submitted |
datetime | Submission timestamp. For worked time, this is normally the comment creation time. |
updated |
datetime | Time when the record was created or last updated. |
hours_estimated |
integer or null | Estimated time in seconds. |
hours_worked |
integer or null | Worked time in seconds. |
hours_avaible |
integer or null | Available capacity in seconds. |
Only the time field corresponding to the selected record type contains a value. The other two time fields are null.
After creating a record, the method:
INSERT eventFor worked-time records, the activity entry is associated with the current user, comment, task, track, and project.
For estimated-time and available-capacity records, the activity entry also includes the relevant target user when one is associated with the record.
Business-rule errors are returned in the regular API response format with operation_status: "ERROR".
| HTTP status | Description |
|---|---|
401 Unauthorized |
The session or token is missing, invalid, or does not belong to the requested account. |
403 Forbidden |
The current user is not permitted to add the requested time type or does not have access to the related project. |
| Error number | Message | Description |
|---|---|---|
2301 |
Comment Not Found |
The comment does not exist, is not active, or does not belong to the current user. |
2302 |
Comment must be in the task |
The selected comment is not associated with a task. |
2303 |
Task Not Found |
The task associated with the worked-time comment was not found. |
2304 |
Record hour_id=... already exists |
Worked time has already been added for the comment. |
2305 |
comment_id is required |
comment_id was not supplied for a worked-time record. |
2308 |
Task Not Found |
The specified task for estimated time was not found. |
2309 |
Record hour_id=... already exists |
Estimated time already exists for the task and track. |
2311 |
Track Not Found |
The specified track was not found. |
2312 |
Project Not Found |
The track is not associated with a project. |
2313 |
User Not Found |
The available-capacity user does not exist or does not belong to the track's project. |
2314 |
Record hour_id=... already exists |
Available capacity already exists for the user and track. |
2315 |
track_id and user_id is required |
track_id or user_id was not supplied for available capacity. |
2316 |
hours_worked or hours_estimated or hours_avaible is required |
No supported time value was provided. |
2317 |
Varies | A time value is outside the supported range, or task_id is missing for estimated time. |
2318 |
Track time within 5 days from time of commenting. |
Worked time can no longer be added because the comment is more than five days old. |
Example error response:
{
"data": {
"operation_status": "ERROR",
"error_no": 2316,
"error_message": "hours_worked or hours_estimated or hours_avaible is required"
}
}
submitted matches the comment creation time rather than the request time.hours_avaible; hours_available is not processed by this method.