POST /clock
A "clock time" is like a stopwatch and after successful save it becomes a normal Time Entry.
Request parameters to START a clock
| Parameter | Type | Description |
|---|---|---|
| action | string | Possible values: "start", "break", "stop", "cancel", "update" |
| dateTime | date | Provide in ISO-8601 format containing a timezone, eg. 2022-04-25T08:00:00+03:00. If action is "start", then this is the dateTime when clock has started. If action is "break" and no break exist, then dateTime is the start time of the break. If action is "break" and a break does exist, then dateTime is the end time of the break. If action is "stop", then this is the dateTime when clock is stoped. |
| userId | string | If provided clock will be assigned for this user. If not provided clock will be assigned to the user who is authenticated and who is making the API call. |
| timeType | string | Possible values: "work", "parental_leave", "worked_rest_period", "clocking", "statutory_leave", "public_holiday_abroad", "medical_leave", "bad_weather", "company_vacation", "unpaid_vacation", "care_leave", "out_office", "work_accident_sickness", "military_exercize", "flextime", "unpaid_time_off", "home_office", "study_leave", "paid_time_off", "other_leave", "vacation_abroad", "travel", "sick", "military_service", "jubilee_day", "vacation", "move", "special_leave", "free_time" |
| comment | string | If provided a comment will be created. |
| organization | Provide "organizationName" OR "organizationId" to which the clock belongs. If you provide both then "organizationName" will be ignored. | |
| organizationName | string | Provide name of organization to which the clock belongs. If two or more organizations have the same name a random of these organizations will be chosen. Provide either a "organizationName" or an "organizationId". If you provide both then "organizationName" will be ignored. |
| organizationId | string | Provide id of organization. Contrary to the "organizationName" the id of the organization is unique and should be a preferred use. |
Clocking Times
One user can only have one clocking time simultaneously.
Request JSON example for start action:
{
"dateTime": "2022-05-06T09:05:35+03:00",
"organizationName": "Test Project",
"organizationId": "c8abcde9-55fe-4019-9846-54bfaa94ec10",
"action": "start",
"timeType": "work",
"comment": "Test",
"userId": "c9abc5d9-7c28-42a0-99fa-aae3f51a47b3"
}
Request JSON example for break action:
{
"dateTime": "2022-05-06T09:07:52+03:00",
"action": "break",
"userId": "c9b695d9-7c28-42a0-99fa-aae3f51a47b3"
}
Request JSON example for stop action:
{
"dateTime": "2022-05-06T09:10:48+03:00",
"action": "stop",
"userId": "c9b695d9-7c28-42a0-99fa-aae3f51a47b3"
}
Request JSON example for cancel action:
{
"action": "cancel", //cancel action will discard the running clock from this user.
"userId": "c9b695d9-7c28-42a0-99fa-aae3f51a47b3"
}
Request JSON example for update action:
{
"action": "update",
"organizationName": "Project XYZ", //if provided then the assigned organization to the clock will be updated.
"organizationId": "c8abcde9-55fe-4019-9846-54bfaa94ec10", //if provided then the assigned organization to the clock will be updated.
"timeType": "work", //if provided then the assigned timeType to the clock will be updated.
"userId": "c9b695d9-7c28-42a0-99fa-aae3f51a47b3"
}
Overwriting time entries
Once a clock is stoped it becomes a normal time entry. If a time entry overlap with an existing time entry, then new time entry will be created and existing one will be removed. In case that the existing time entry is already "approved", then you will get back an error that new time entry could not be saved and the clock time will become an invalid clocking time entry.
Invalid Clocking Times
In case that a clock time could not be saved successfully, it becomes an invalid clocking time entry which can be deleted via DELETE /times method by providing the id.
Responses
| Code | Title | Description |
|---|---|---|
| 200 | Success | Returned if request was successful. |
| 201 | Success | Returned if request was successful but time entry was overwritten or trimmed or otherwise edited. |
| 400 | Bad Request | Returned if request was bad. |
| 401 | Unauthorized | Returned if request was not authorized (eg. due to bad API key). |
| 404 | Not Found | Returned if request could not be found. |
Response JSON example:
{
"items": [
{
"message": "Success",
"data": {
"id": "85561232-4ca4-4a0e-80d8-844be70aa0b3",
"from": "2022-04-22T10:40:00+03:00",
"to": "2022-04-22T18:40:00+03:00",
"breaks": [
{
"id": "59876501-5c90-467e-a4d4-b86ad14a5dcb",
"from": "2022-04-22T10:40:00+03:00",
"to": "2022-04-22T18:40:00+03:00",
"automatic": false //true or false if autmatic breaks were saved through target times.
}
],
"comment": "Test Comment",
"type": "work",
"organizationName": "Project ABC",
"userId": "12341232-4ca4-4a0e-80d8-844be70aa0b3",
"category": "productive", //category of timeType, possible responses "productive", "unproductive", "vacation", "sick", "paid_leave", "unpaid_leave"
"creationType": "clock" //possible responses "times", "clock", "wtm" or "null". "times" will be returned if time entry was saved manually with from-to times. "clock" will be returned if time entry was clocked. "wtm" will be returned if time entry was saved automatically via the working time model. "null" will be returned if time entry was edited.
}
}
],
"valid": true //true if successful, false if not
}
Users permissions will be considered
The response will consider the permissions of the user who is authenticated by the API call and will only return time entries which user is allowed to see.