Create a time-tracking booking

Records a new attendance booking for an employee and runs the same plausibility checks (e.g. overlapping bookings, absence conflicts) applied when booking through the UI.

Availability: Full version and ZEP Clock

Request

POST /api/v1/attendances

curl --request POST \
     --url 'https://www.zep-online.de/zepinstanz/next/api/v1/attendances' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer {token}' \
     --header 'Content-Type: application/json' \
     --data '{
       "employee_id": "max.mustermann",
       "date": "2024-07-20T00:00:00.000000Z",
       "from": "string",
       "to": "string",
       "duration": 1.5,
       "locked": false,
       "is_travel": false,
       "billable": true,
       "work_location_is_project_relevant": true,
       "color": "#664599",
       "project_task_id": 1.5,
       "project_id": 16,
       "activity_id": "im",
       "start": "Location A",
       "destination": "Location B",
       "vehicle_id": 3,
       "private": true,
       "km": 120,
       "passengers": 2,
       "direction_of_travel": 0,
       "work_location_id": "string",
       "note": "Familienurlaub"
     }'

Request body

Name
employee_id
Type
string, required
Description
Username of the employee this booking is recorded for.
Name
date
Type
string (date-time), required
Description
Calendar day the booking belongs to.
Name
from
Type
string, required
Description
Time the booking starts.
Name
to
Type
string, required
Description
Time the booking ends. A value of 00:00 marks a booking that runs past midnight.
Name
duration
Type
number, nullable
Description
Booked duration in hours, required when time recording is duration-only.
Name
locked
Type
boolean, nullable
Description
Whether the booking is locked against further edits.
Name
is_travel
Type
boolean, nullable
Description
Whether the booking represents travel time rather than regular work.
Name
billable
Type
boolean, nullable
Description
Whether the booked time is billable to the customer.
Name
work_location_is_project_relevant
Type
boolean, nullable
Description
Whether the work location matters for whether this booking counts as billable.
Name
color
Type
string, nullable
Description
Display color used to highlight the booking in calendar views.
Name
project_task_id
Type
number, required
Description
Identifier of the project task the booked time is recorded against.
Name
project_id
Type
number, required
Description
Identifier of the project the booked time is recorded against.
Name
activity_id
Type
string, required
Description
Identifier of the activity performed during the booking.
Name
start
Type
string, nullable
Description
Starting point of the travel this booking records, only set for travel bookings.
Name
destination
Type
string, nullable
Description
Destination of the travel this booking records, only set for travel bookings.
Name
vehicle_id
Type
number, nullable
Description
Identifier of the vehicle used for the travel this booking records.
Name
private
Type
boolean, nullable
Description
Whether the travel this booking records was for private purposes.
Name
km
Type
number, nullable
Description
Distance traveled, in kilometers.
Name
passengers
Type
number, nullable
Description
Number of passengers carried during the travel this booking records.
Name
direction_of_travel
Type
integer, nullable
Description
Direction of the travel this booking records (outbound or return).
One of: 0, 1, 2
Name
work_location_id
Type
string, nullable
Description
Identifier of the project location this booking was made at.
Name
note
Type
string, nullable
Description
Free-text note attached to the booking.

Response

{
  "data": {
    "id": 1,
    "date": "2024-07-20T00:00:00.000000Z",
    "from": "string",
    "to": "string",
    "end_date": "2024-01-16T00:00:00.000000Z",
    "employee_id": "max.mustermann",
    "duration": 1.5,
    "note": "Familienurlaub",
    "issue_id": "string",
    "department_id": 1,
    "project_release": {
      "id": 1,
      "name": "unchanged"
    },
    "project_released_at": "2024-06-24 17:46:25",
    "project_released_by": "max.mustermann",
    "billable": true,
    "work_location_id": "string",
    "activity_id": "im",
    "start": "Location A",
    "destination": "Location B",
    "vehicle_id": "string",
    "private": true,
    "passengers": 2,
    "km": 120,
    "direction_of_travel": {
      "id": 1,
      "name": "outward"
    },
    "project_id": 16,
    "project_task_id": 1,
    "invoice_item_id": 1,
    "ticket_id": 1234,
    "subtask_id": 1,
    "work_location_is_project_relevant": true,
    "created": "2024-07-20T11:30:00.000000Z",
    "modified": "2024-07-20T12:30:00.000000Z"
  }
}

Response fields

Name
id
Type
integer
Description
Unique identifier of the booking.
Name
date
Type
string (date-time)
Description
Calendar day the booking belongs to.
Name
from
Type
string
Description
Time the booking starts.
Name
to
Type
string
Description
Time the booking ends. A value of 00:00 marks a booking that runs past midnight — see end_date for the calendar day it actually ends on.
Name
end_date
Type
string
Description
Calendar day the booking actually ends on. to alone is ambiguous for a Tagesende booking (stored as to=‘00:00:00’ same date but meaning next day, see Attendance::toAsCarbon()) — this makes that rollover explicit for API consumers/connectors without changing the existing to/from/date format (SQ2-366).
Name
employee_id
Type
string
Description
Username of the employee this booking belongs to.
Name
duration
Type
number
Description
Booked duration in hours, derived from from and to.
Name
note
Type
string, nullable
Description
Free-text note attached to the booking.
Name
issue_id
Type
string, nullable
Description
Free-text reference to an external ticket/issue this booking relates to. Only on instances with the MOD_PROXORA extension. Not a generally available feature.
Name
department_id
Type
integer
Description
The department the employee was assigned to when the booking was made. Only with the Departments module (MOD_ABT).
Name
project_release
Type
object, nullable
Description
Approval state of the project-release workflow for this booking. Only present when project release is required by configuration.
Name
project_release.id
Type
integer
Description
The stored value. Compare against this, not against name.
Name
project_release.name
Type
string
Description
The human-readable label, delivered in the tenant’s language. Do not parse it.
One of: "unchanged", "zu prüfen", "freigegeben", "abgerechnet"
Name
project_released_at
Type
string (date-time), nullable
Description
Timestamp of when the project release for this booking was granted. Only present when project release is required by configuration.
Name
project_released_by
Type
string, nullable
Description
Username of the employee who granted the project release for this booking. Only present when project release is required by configuration.
Name
billable
Type
boolean
Description
Indicates whether the time entry is billable.
Name
work_location_id
Type
string, nullable
Description
ID of the work location. Must exist.
Name
activity_id
Type
string
Description
The ID of the associated activity.
Name
start
Type
string, nullable
Description
Starting point of the trip.
Name
destination
Type
string, nullable
Description
Destination of the trip.
Name
vehicle_id
Type
string, nullable
Description
The ID of the vehicle used.
Name
private
Type
boolean, nullable
Description
Indicates whether the trip was private.
Name
passengers
Type
integer, nullable
Description
Number of passengers.
Name
km
Type
integer, nullable
Description
Distance traveled in kilometers.
Name
direction_of_travel
Type
object, nullable
Description
Direction of travel (e.g. continue).
Name
direction_of_travel.id
Type
integer
Description
The stored value. Compare against this, not against name.
Name
direction_of_travel.name
Type
string
Description
The human-readable label, delivered in the tenant’s language. Do not parse it.
One of: "outward", "continue", "return"
Name
project_id
Type
integer
Description
The ID of the related project.
Name
project_task_id
Type
integer
Description
The ID of the related project task.
Name
invoice_item_id
Type
integer, nullable
Description
The ID of the invoice item this booking was billed on, once it has been invoiced.
Name
ticket_id
Type
integer, nullable
Description
The ID of the ticket this booking belongs to.
Name
subtask_id
Type
integer, nullable
Description
The ID of the ticket subtask this booking belongs to.
Name
work_location_is_project_relevant
Type
boolean
Description
Indicates whether the work location is project-related.
Name
created
Type
string (date-time), nullable
Description
Timestamp of when the booking was created.
Name
modified
Type
string (date-time), nullable
Description
Timestamp of when the booking was last changed.

Generated from the OpenAPI specification — edit the source code, not this page.

GET Get a single time-tracking booking PATCH Update a time-tracking booking