REST-API

The clockodo API allows you to connect clockodo to other systems. Accounting and project management applications or proprietary shell scripts are examples of useful mash-ups with clockodo.

api/userreports: Get co-worker reports

With this resource, you can access all information which you know from the co-worker reports.

For example the working time evaluation of each day, as well es the holiday account of each co-worker.


Object type „userreport“

Please note, that the property »month_details« of the object type »userreport« can contain an array of further objects of type "userreport_month", so that a nested array structure gets generated.

See also this example of a return.

Parameter Type Description
users_id integer ID of the corresponding co-worker
users_name string Name of the corresponding co-worker
sum_target integer Planned work time for the year (in seconds)
sum_hours integer Worked time in the year (in seconds)
sum_reduction integer Sum of overtime reductions in the year (in seconds)
sum_reduction_planned integer Sum of planned overtime reductions in the rest of the year (in seconds)
overtime_carryover integer Overtime carryover for the year (in seconds)
overtime_reduced integer Withdrawed overtime for the year (in seconds)
diff integer Calculated difference of the time account of the year (in seconds)
holidays_quota float Holiday quota for the year
holidays_carry float Holiday carryover for the year
holidays_used float Number of used holidays in the year
special_holidays float Number of days of special leaves in the year
sickdays float Number of sick days in the year
month_details Array of objects of the type "userreport_month" Only if month details are requested

Object type „userreport_month“

 

This object type gets used in the property »month_details« of the object type »userreport«.

Parameter Type Description
nr integer Month number (1 to 12)
sum_target integer Planned work time (in seconds)
sum_hours integer Worked time (in seconds)
sum_hours_without_ compensation integer Worked time when ignoring the monthly compensation (in seconds)
sum_reduction integer Sum of overtime reductions (in seconds)
diff integer Calculated difference of the time account (in seconds)
week_details Array of objects of the type "userreport_week" Only if week details are requested

Object type „userreport_week“

 

This object type gets used in the property »week_details« of the object type »userreport_month«.

Parameter Type Description
nr integer Week number (following ISO 8601)
sum_target integer Planned work time (in seconds)
sum_hours integer Worked time (in seconds)
sum_reduction integer Sum of overtime reductions (in seconds)
diff integer Calculated difference of the time account (in seconds)
day_details Array of objects of the type "userreport_day" Only if day details are requested

Object type „userreport_day“

 

This object type gets used in the property »day_details« of the object type »userreport_week«.

Parameter Type Description
date string Date (YYYY-MM-DD)
weekday integer Number, which identificates the week day
nonbusiness boolean Is the day a nonbusiness day?
count_sick float Absence because of sickness (0, 0.5 or 1)
count_regular_holidays float Absence because of a regular holiday (0, 0.5 or 1)
count_special_leaves float Absence because of special leaves (0, 0.5 or 1)
count_holidays float Absence because of a regular holiday or special leaves (0, 0.5 or 1) = "count_regular_holidays" + "count_special_leaves"
count_ot_reduction integer Overtime reduction on this day (in seconds)
target integer Planned work time (in seconds)
target_raw integer Planned work time which would have been calculated if no nunbusiness day or absence had reduced the planned work time (in seconds)
hours integer Worked time (in seconds) Won't be added for future days
hours_without_ compensation integer Worked time when ignoring the daily compensation (in seconds) Won't be added for future days
diff integer Calculated difference of the time account (in seconds) Won't be added for future days
work_start string Begin of the work time in format "YYYY-MM-DD HH:II:SS" Only if requested (report type “4”); won't be added for future days
work_end string End of the work time in format "YYYY-MM-DD HH:II:SS" Only if requested (report type “4”), won't be added for future days
breaks array Breaks which habe been made (Subarray keys: [string] since, [string] until, [integer] length) Only if requested (report type “4”), won't be added for future days

Query co-worker reports for all co-workers

Request
GET /api/userreports
Required parameters year (integer)
Optional parameters type 0: Request only key data for the year (default)
1: Request key data for the year and the months
2: Request key data for the year, months and weeks
3: Request key data for the year, months, weeks and days
4: Request key data for the year, months, weeks and days; The day data does also include start and end times, as well as breaks
Response
{
  "userreports": 
  [
    [object of type userreport],
    [object of type userreport], 
    ...
  ]
}
Example of a nested response with all details
{
  "userreports": 
  [
    {
      'id' : 123,
      'name': 'John Doe',
      'sum_target': 1419,
      ...
      'month_details' : 
      [
      	{
          'nr': 1,
          'sum_target': 142,
          ...,
          'week_details': 
          [
            {
              'nr': 1,
              'sum_target': 40,
              ...
              'day_details': 
              [
                {
                  'date': '2016-01-01',
                  'weekday': 5,
                  ...
                },
                {
                  'date': '2016-01-01',
                  'weekday': 6,
                  ...
                },
                ...
                [FURTHER DAYS OF THE WEEK]
              ]
            },
            {
              'nr': 2,
              'sum_target': 40,
              ...
              'day_details': 
              [
                {
                  'date': '2016-01-04',
                  'weekday': 1,
                  ...
                },
                {
                  'date': '2016-01-05',
                  'weekday': 2,
                  ...
                },
                ...
                [FURTHER DAYS OF THE WEEK]
              ]
            },
            ... 
            [FURTHER WEEKS]
          ]
      	},
      	...
      	[FURTHER MONTHS]
      ]
    },
    ...
    [FURTHER REPORTS TO CO-WORKERS]
  ]
}

Query the co-worker report for a selected co-worker

Request
GET /api/userreports/[Users-ID]
Required parameters year (integer)
Optional parameters type 0: Request only key data for the year (default)
1: Request key data for the year and the months
2: Request key data for the year, months and weeks
3: Request key data for the year, months, weeks and days
4: Request key data for the year, months, weeks and days; The day data does also include start and end times, as well as breaks
Response
{
  "userreport": [object of type userreport]
}

Please see also the information in the section »Query co-worker reports for all co-workers«.