Clockodo User Report API

openapi: 3.2.0
info:
  title: Clockodo API Documentation User Report API
  description: '# Clockodo REST API


    Our API opens Clockodo for other systems. Billing and project management applications or custom shell scripts, for example, are useful mash-ups with Clockodo. As a REST API, the interface allows you to query and modify Clockodo data and control the clock via HTTP in JSON format. ## URL of the Clockodo API


    You can access our API via the following URL:


    ```text

    https://my.clockodo.com/api/[resource type]

    ```


    The resource type represents a class of your data. Once you request a specific resource, for example, query information about exactly one entity, you can use the following URL:


    ```text

    https://my.clockodo.com/api/[resource type]/[resource ID]

    ```


    In the following sections of this documentation, you will find more detailed descriptions of the available endpoints for each resource type. For example, under Entry you will find detailed information on how you can manage time entries in your Clockodo environment. ## HTTP Verbs


    To tell the API which operations you want to perform on the resources, the so-called verbs of the HTTP protocol are used. The following operations are usually possible:


    | HTTP Verb | Description |

    |-----------------------------|-----------------------------------------------------------------|

    | `GET` | Query a list of all the resources of the selected resource type |

    | `GET` (with resource ID) | Query exactly one resource |

    | `POST` | Create a new resource |

    | `PUT` (with resource ID) | Update or edit a resource |

    | `DELETE` (with resource ID) | Delete a resource |


    ## Authentication


    Clockodo supports two authentication approaches:


    - **API key authentication**, using a Clockodo user''s email address and personal API key. The credentials can be sent either via HTTP Basic authentication or via Clockodo-specific HTTP headers. - **OAuth 2.0**, using delegated access with scoped bearer tokens. ### API key authentication


    Each Clockodo user has personal API access that takes the user''s access rights into account. You can find your API key under the menu item "Personal data" in your Clockodo account. Changing your Clockodo password invalidates your existing API key. If you use the API key for an integration, you must update the integration with the new API key after changing your password. #### HTTP Basic authentication


    To access your data via the API, authenticate using your email address and API key with the basic authentication mechanism of the HTTP protocol:


    ```text

    User: [email address]

    Password: [API key]

    ```


    Basic authentication is transmitted in the `Authorization` HTTP header. Most HTTP clients generate this header automatically from the credentials above:


    ```http

    Authorization: Basic

    ```


    **Example:** For the user `admin@clockodo.com` with the API key `nl9tzwlwr4kzmd1qcbmtli60jpwd2c9g`, the header is:


    ```http

    Authorization: Basic YWRtaW5AY2xvY2tvZG8uY29tOm5sOXR6d2x3cjRrem1kMXFjYm10bGk2MGpwd2QyYzln

    ```


    #### Clockodo API headers


    Alternatively, you can send the same credentials using Clockodo-specific HTTP headers:


    ```http

    X-ClockodoApiUser: [email address]

    X-ClockodoApiKey: [API key]

    ```


    #### Client identification


    Requests using either of the API-key authentication methods described above must also identify the calling application and provide the email address of a technical contact person. For this purpose, include the following HTTP header with every request:


    ```http

    X-Clockodo-External-Application: [name of application or company];[email address]

    ```


    **Example:**


    ```http

    X-Clockodo-External-Application: Clockodo;admin@clockodo.com

    ```


    This header is not required for requests authenticated with an OAuth bearer token. ### OAuth 2.0


    Clockodo supports OAuth 2.0 for integrations that use delegated access with scoped bearer tokens. It is accepted across the whole API as an alternative to API key authentication. Every access token is tied to a Clockodo user and is subject to that user''s access rights, just like an API key.'
  termsOfService: https://www.clockodo.com/en/terms-and-conditions/
  contact:
    name: Clockodo support
    url: https://www.clockodo.com/en/about-us/
    email: support@clockodo.com
  version: '2026-10-16'
  x-logo:
    url: /clockodo-logo.svg
    href: /
    altText: Clockodo Logo
    backgroundColor: '#3d2a5a'
servers:
- url: https://my.clockodo.com/api
security:
- BasicAuth: []
  ExternalApp: []
- User: []
  Key: []
  ExternalApp: []
- OAuth2: []
tags:
- name: UserReport
  description: Query user reports (e. g. work time evaluation of each day and holiday account of each co-worker)
paths:
  /userreports:
    get:
      tags:
      - UserReport
      operationId: getUserreports
      parameters:
      - name: type
        in: query
        description: 'Possible values:

          - `0`: Only for year (default)

          - `1`: For year and months

          - `2`: For year, months and weeks

          - `3`: For year, months, weeks and days

          - `4`: For year, months, weeks and days; including start and end times and breaks'
        required: false
        schema:
          $ref: '#/components/schemas/UserReportType'
      - name: year
        in: query
        required: true
        schema:
          type: integer
          maximum: 2027
          minimum: 1910
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                required:
                - userreports
                properties:
                  userreports:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserReportV1'
                type: object
      deprecated: false
      summary: Get userreports
      x-summary-source: derived
  /userreports/{id}:
    get:
      tags:
      - UserReport
      operationId: getUserreportById
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
          examples:
          - 1
      - name: type
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/UserReportType'
      - name: year
        in: query
        required: true
        schema:
          type: integer
          maximum: 2027
          minimum: 1910
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                required:
                - userreport
                properties:
                  userreport:
                    $ref: '#/components/schemas/UserReportV1'
                type: object
      deprecated: false
      summary: Get userreport by id
      x-summary-source: derived
components:
  schemas:
    UserReportAbsenceSummaryV1:
      required:
      - regular_holidays
      - sick_self
      - sick_child
      - special_leaves
      - school
      - maternity_protection
      - home_office
      - out_of_office
      - quarantine
      - military_service
      properties:
        regular_holidays:
          type: number
          format: float
        sick_self:
          type: number
          format: float
        sick_child:
          type: number
          format: float
        special_leaves:
          type: number
          format: float
        school:
          type: number
          format: float
        maternity_protection:
          type: number
          format: float
        home_office:
          type: number
          format: float
        out_of_office:
          type: number
          format: float
        quarantine:
          type: number
          format: float
        military_service:
          type: number
          format: float
      type: object
    UserReportBreakItemV1:
      required:
      - since
      - until
      - length
      properties:
        since:
          type: string
          format: date-time
        until:
          type: string
          format: date-time
        length:
          type: number
          format: float
      type: object
    UserReportType:
      title: User report type
      description: 'Possible values:

        - `0`: Year

        - `1`: Month

        - `2`: Week

        - `3`: Day

        - `4`: DayWithWorkTime'
      type: integer
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      x-enumNames:
      - Year
      - Month
      - Week
      - Day
      - DayWithWorkTime
    UserReportDayDetailV1:
      required:
      - date
      - weekday
      - nonbusiness
      - count_absence
      - count_reduction_used
      - target
      - target_raw
      - surcharges
      properties:
        date:
          type: string
          format: date
        weekday:
          type: integer
        nonbusiness:
          type: boolean
        count_absence:
          $ref: '#/components/schemas/UserReportAbsenceSummaryV1'
        count_reduction_used:
          type:
          - number
          - 'null'
          format: float
        target:
          type:
          - number
          - 'null'
          format: float
        target_raw:
          type:
          - number
          - 'null'
          format: float
        surcharges:
          $ref: '#/components/schemas/UserReportSurchargeSummaryV1'
        hours:
          type:
          - number
          - 'null'
          format: float
        hours_without_compensation:
          type:
          - number
          - 'null'
          format: float
        diff:
          type:
          - number
          - 'null'
          format: float
        breaks:
          type: array
          items:
            $ref: '#/components/schemas/UserReportBreakItemV1'
        work_start:
          type:
          - string
          - 'null'
          format: date-time
        work_end:
          type:
          - string
          - 'null'
          format: date-time
      type: object
    UserReportV1:
      required:
      - users_id
      - users_name
      - users_number
      - users_email
      - sum_target
      - sum_hours
      - sum_reduction_used
      - sum_reduction_planned
      - overtime_carryover
      - overtime_reduced
      - diff
      - holidays_quota
      - holidays_carry
      - sum_absence
      - surcharges
      - workdays
      - month_details
      properties:
        users_id:
          type: integer
        users_name:
          type: string
        users_number:
          title: Personnel number
          type:
          - string
          - 'null'
        users_email:
          type: string
        sum_target:
          title: Planned work time for the year
          description: In seconds
          type:
          - number
          - 'null'
          format: float
        sum_hours:
          title: Work time in the year
          description: In seconds
          type: number
          format: float
        sum_reduction_used:
          title: Sum of overtime reductions in the year
          description: In seconds
          type: number
          format: float
        sum_reduction_planned:
          title: Sum of planned overtime reductions in the rest of the year
          description: In seconds
          type: number
          format: float
        overtime_carryover:
          title: Overtime carryover for the year
          description: In seconds
          type: number
          format: float
        overtime_reduced:
          title: Overtime reduced for the year
          description: In seconds
          type: number
          format: float
        diff:
          title: Calculated difference of the work time of the year
          description: In seconds
          type: number
          format: float
        holidays_quota:
          title: Vacation quota for the year
          type: number
          format: float
        holidays_carry:
          title: Vacation carryover for the year
          type: number
          format: float
        sum_absence:
          $ref: '#/components/schemas/UserReportAbsenceSummaryV1'
          title: Sum of absence days by type
        surcharges:
          $ref: '#/components/schemas/UserReportSurchargeSummaryV1'
        workdays:
          type: number
          format: float
        month_details:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/UserReportMonthDetailV1'
      type: object
    UserReportWeekDetailV1:
      required:
      - nr
      - sum_target
      - sum_hours
      - sum_reduction_used
      - diff
      - surcharges
      - day_details
      properties:
        nr:
          type: integer
        sum_target:
          type:
          - number
          - 'null'
          format: float
        sum_hours:
          type: number
          format: float
        sum_reduction_used:
          type:
          - number
          - 'null'
          format: float
        diff:
          type:
          - number
          - 'null'
          format: float
        surcharges:
          $ref: '#/components/schemas/UserReportSurchargeSummaryV1'
        day_details:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/UserReportDayDetailV1'
      type: object
    UserReportMonthDetailV1:
      required:
      - nr
      - sum_target
      - sum_hours
      - sum_hours_without_compensation
      - sum_reduction_used
      - sum_overtime_reduced
      - diff
      - surcharges
      - week_details
      properties:
        nr:
          type: integer
        sum_target:
          type:
          - number
          - 'null'
          format: float
        sum_hours:
          type: number
          format: float
        sum_hours_without_compensation:
          type: number
          format: float
        sum_reduction_used:
          type:
          - number
          - 'null'
          format: float
        sum_overtime_reduced:
          type: number
          format: float
        diff:
          type: number
          format: float
        surcharges:
          $ref: '#/components/schemas/UserReportSurchargeSummaryV1'
        week_details:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/UserReportWeekDetailV1'
      type: object
    UserReportSurchargeSummaryV1:
      required:
      - saturday
      - sunday
      - nonbusiness
      - nonbusiness_special
      - night
      - night_increased
      properties:
        saturday:
          type: number
          format: float
        sunday:
          type: number
          format: float
        nonbusiness:
          type: number
          format: float
        nonbusiness_special:
          type: number
          format: float
        night:
          type: number
          format: float
        night_increased:
          type: number
          format: float
      type: object
  securitySchemes:
    BasicAuth:
      type: http
      description: The basic authentication of the HTTP protocol. Credentials are email address and API key.<br />Every co-worker will find his API key in the menu item "Personal data" in his Clockodo account.
      scheme: basic
    User:
      type: apiKey
      description: 'Must be filled together with <code>X-ClockodoApiKey</code><br /><strong>Example: admin@clockodo.com</strong>'
      name: X-ClockodoApiUser
      in: header
    Key:
      type: apiKey
      description: Must be filled together with <code>X-ClockodoApiUser</code>
      name: X-ClockodoApiKey
      in: header
    ExternalApp:
      type: apiKey
      description: 'Every request to our API must provide identification of the calling application, including the email address of a technical contact person.<br /><strong>Example: "Clockodo;admin@clockodo.com"</strong>'
      name: X-Clockodo-External-Application
      in: header
    OAuth2:
      type: oauth2
      description: OAuth 2.0 for external integrations via authorization code flow with refresh tokens. OAuth clients can be provisioned via Dynamic Client Registration (POST /oauth/register) or Client ID Metadata Documents (CIMD). Dynamically registered clients are deleted after 90 days without any token or authorization code activity; store the issued client_id and client_secret permanently, as the secret is only returned once.
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /token
          refreshUrl: /token
          scopes:
            full_access: Full access to all API endpoints
            accessGroups:read: Read access group data
            accessGroups:write: Write access group data
            absences:read: Read absence data
            absences:write: Write absence data
            browserExtensionRules:read: Read browser extension rule data
            browserExtensionRules:write: Write browser extension rule data
            clock:read: Read clock data
            clock:write: Write clock data
            company:read: Read company data
            customers:read: Read customer data
            customers:write: Write customer data
            entryGroups:read: Read entry group data
            entryGroups:write: Write entry group data
            entries:read: Read time entry data
            entries:write: Write time entry data
            entriesTexts:read: Read time entry text data
            entriesTexts:write: Write time entry text data
            holidaysCarry:read: Read holiday carryover data
            holidaysCarry:write: Write holiday carryover data
            holidaysQuota:read: Read holiday quota data
            holidaysQuota:write: Write holiday quota data
            lumpSumServices:read: Read lump sum service data
            lumpSumServices:write: Write lump sum service data
            nonbusinessDays:read: Read nonbusiness day data
            nonbusinessDays:write: Write nonbusiness day data
            nonbusinessGroups:read: Read nonbusiness group data
            nonbusinessGroups:write: Write nonbusiness group data
            overtimeCarry:read: Read overtime carryover data
            overtimeCarry:write: Write overtime carryover data
            overtimeReductions:read: Read overtime reduction data
            overtimeReductions:write: Write overtime reduction data
            projects:read: Read project data
            projects:write: Write project data
            rates:read: Read rate data
            rates:write: Write rate data
            services:read: Read service data
            services:write: Write service data
            subprojects:read: Read subproject data
            subprojects:write: Write subproject data
            subscription:read: Read subscription data
            targetHours:read: Read planned hours data
            targetHours:write: Write planned hours data
            teams:read: Read team data
            teams:write: Write team data
            userReports:read: Read co-worker report data
            users:read: Read co-worker data
            users:write: Write co-worker data
            usersNonbusinessDays:read: Read co-worker nonbusiness day data
            usersNonbusinessGroups:read: Read co-worker nonbusiness group data
            usersNonbusinessGroups:write: Write co-worker nonbusiness group data
            workTimes:read: Read work time data
            workTimes:write: Write work time data
x-provenance:
  method: harvested
  publisher: Clockodo
  source: https://docs.clockodo.com/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)