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
users_number	string	Personnel number of the corresponding co-worker
users_email	string	Email address 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_used	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
sum_absence[regular_holidays]	float	Number of used holidays
sum_absence[sick_self]	integer	Number of sick days
sum_absence[sick_child]	integer	Number of sick days of a child
sum_absence[special_leaves]	float	Number of days of special leaves
sum_absence[school]	float	Number of days of school
sum_absence[maternity_protection]	float	Number of days of maternity protection
sum_absence[home_office]	float	Number of days of home office
sum_absence[out_of_office]	float	Number of days out of office
sum_absence[quarantine]	integer	Number of days of quarantine
sum_absence[military_service]	integer	Number of days of military / alternative service
holidays_used	float	Number of used holidays DEPRECATED. This column won't be delivered after 01.01.2020.
special_holidays	float	Number of days of special leaves in the year DEPRECATED. This column won't be delivered after 01.01.2020.
sickdays	float	Number of sick days in the year DEPRECATED. This column won't be delivered after 01.01.2020.
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_used	integer	Sum of overtime reductions (in seconds)
sum_overtime_reduced	int	Sum of withdrawed / payed out overtime
diff	integer	Calculated difference of the time account (in seconds)
sum_reduction	null	Delivers null due to backward compatibility reasons DEPRECATED. This column won't be delivered after 01.01.2020.
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_used	integer	Sum of overtime reductions (in seconds)
diff	integer	Calculated difference of the time account (in seconds)
sum_reduction	null	Delivers null due to backward compatibility reasons. DEPRECATED. This column won't be delivered after 01.01.2020.
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?
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 (e.g. in format “YYYY-MM-DD HH:MM:SS”; see section “Localisation”) Only if requested (report type “4”); won't be added for future days
work_end	string	End of the work time (e.g. in format “YYYY-MM-DD HH:MM:SS”; see section “Localisation”) 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
count_absence[regular_holidays]	float	Absence because of a regular holiday or special leaves (0, 0.5 or 1)
count_absence[sick_self]	int	Absence because of sickness (0 or 1)
count_absence[sick_child]	int	Absence because of sickness of a child (0 or 1)
count_absence[special_leaves]	float	Absence because of special leaves (0, 0.5 or 1)
count_absence[school]	float	Absence because of school / further education (0, 0.5 or 1)
count_absence[maternity_protection]	float	Absence because of maternity protection (0, 0.5 or 1)
count_absence[home_office]	float	Home office (0, 0.5 or 1)
count_absence[out_of_office]	float	Work out of office (0, 0.5 or 1)
count_absence[quarantine]	integer	Absence because of quarantine (0 or 1)
count_absence[military_service]	integer	Absence because of military / alternative service (0 or 1)
count_reduction_used	integer	Overtime reduction on this day (in seconds)
count_holidays	float	Absence because of a regular holiday or special leaves (0, 0.5 or 1) DEPRECATED. This column won't be delivered after 01.01.2020.
count_regular_holidays	float	Absence because of a regular holiday (0, 0.5 or 1) DEPRECATED. This column won't be delivered after 01.01.2020.
count_special_leaves	float	Absence because of special leaves (0, 0.5 or 1) DEPRECATED. This column won't be delivered after 01.01.2020.
count_sick	float	Absence because of sickness (0, 0.5 or 1) DEPRECATED. This column won't be delivered after 01.01.2020.
count_ot_reduction	null	Delivers null due to backward compatibility reasons. DEPRECATED. This column won't be delivered after 01.01.2020.

Query co-worker reports for all co-workers

Request

GET /api/userreports

Required parameters	year	integer

Optional parameters	type	integer	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«.