Clockodo Clock API

openapi: 3.2.0
info:
  title: Clockodo API Documentation Clock 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: Clock
  description: Control the clock
paths:
  /v2/clock:
    get:
      tags:
      - Clock
      operationId: getClockV2
      parameters:
      - name: users_id
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClockV2'
      deprecated: false
      summary: Get clock V2
      x-summary-source: derived
    post:
      tags:
      - Clock
      operationId: createClockV2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - customers_id
              - services_id
              properties:
                customers_id:
                  type: integer
                  minimum: 1
                services_id:
                  type: integer
                  minimum: 1
                billable:
                  oneOf:
                  - $ref: '#/components/schemas/Billable'
                    description: For companies that restrict who may set the billability of time entries, the value is ignored for users without the right "Set billability of time entries"; the billability is then derived from the default of the project or, without a project, of the customer.
                  - type: 'null'
                  description: For companies that restrict who may set the billability of time entries, the value is ignored for users without the right "Set billability of time entries"; the billability is then derived from the default of the project or, without a project, of the customer.
                clear_overlaps:
                  description: 'Resolve overlaps caused by a backdated clock start ("time_since" in the past): existing time entries within the resulting period are deleted, entries crossing the clock start are shortened to it. Entries reaching beyond the current time stay untouched. Requires "time_since".'
                  type: boolean
                clocked_now:
                  description: The clock was punched now, while "time_since" only sets the start of the entry. Use it for a backdated start performed by a present user, so the entry is not recorded as clocked offline. Without it a backdated start is treated as an offline recording, which is what the offline synchronization needs. An explicitly supplied "time_clocked_since" always wins. Requires "time_since".
                  type: boolean
                duration_transfer:
                  type:
                  - integer
                  - 'null'
                  minimum: 0
                projects_id:
                  type:
                  - integer
                  - 'null'
                  minimum: 0
                subprojects_id:
                  type:
                  - integer
                  - 'null'
                  minimum: 0
                text:
                  type:
                  - string
                  - 'null'
                  maxLength: 1000
                time_since:
                  type:
                  - string
                  - 'null'
                  format: date-time
                  examples:
                  - '2023-02-28T12:00:00Z'
                users_id:
                  type:
                  - integer
                  - 'null'
                  minimum: 1
              type: object
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClockStartV2'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralErrors'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralErrors'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralErrors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralErrors'
      deprecated: false
      summary: Create clock V2
      x-summary-source: derived
  /v2/clock/{id}:
    put:
      tags:
      - Clock
      operationId: updateClockByIdV2
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
          examples:
          - 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - required:
                - time_since
                properties:
                  time_since:
                    type: string
                    format: date-time
                    examples:
                    - '2023-02-28T12:00:00Z'
                  time_since_before:
                    type:
                    - string
                    - 'null'
                    format: date-time
                    examples:
                    - '2023-02-28T12:00:00Z'
                  time_until_before:
                    type:
                    - string
                    - 'null'
                    format: date-time
                    examples:
                    - '2023-02-28T12:00:00Z'
                type: object
              - required:
                - duration
                - duration_before
                properties:
                  time_since_before:
                    type:
                    - string
                    - 'null'
                    format: date-time
                    examples:
                    - '2023-02-28T12:00:00Z'
                  time_until_before:
                    type:
                    - string
                    - 'null'
                    format: date-time
                    examples:
                    - '2023-02-28T12:00:00Z'
                  duration:
                    type: integer
                    minimum: 0
                  duration_before:
                    type: integer
                    minimum: 0
                type: object
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClockDurationV2'
      deprecated: false
      summary: Update clock by id V2
      x-summary-source: derived
    delete:
      tags:
      - Clock
      operationId: deleteClockByIdV2
      parameters:
      - name: away
        in: query
        required: false
        schema:
          type:
          - integer
          - 'null'
          minimum: 0
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
          examples:
          - 1
      - name: start_new
        in: query
        required: false
        schema:
          type:
          - boolean
          - 'null'
      - name: time_until
        in: query
        required: false
        schema:
          type:
          - string
          - 'null'
          format: date-time
          examples:
          - '2023-02-28T12:00:00Z'
      - name: users_id
        in: query
        required: false
        schema:
          type:
          - integer
          - 'null'
          minimum: 1
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClockStopV2'
      deprecated: false
      summary: Delete clock by id V2
      x-summary-source: derived
components:
  schemas:
    EntryV2TimeRunning:
      title: Running Clock Entry
      allOf:
      - $ref: '#/components/schemas/EntryV2TimeBase'
      - required:
        - billable
        - time_until
        - duration
        - clocked
        - time_clocked_since
        properties:
          billable:
            $ref: '#/components/schemas/ApiEntriesV2_Billability'
          time_until:
            title: End date and time
            description: null while the clock is running.
            type: 'null'
          duration:
            title: Duration in seconds
            description: null while the clock is running.
            type: 'null'
          time_clocked_since:
            type: string
            format: date-time
            examples:
            - '2023-02-28T00:00:00Z'
          clocked:
            type: boolean
            enum:
            - true
        type: object
    EntryV2Time:
      title: Time Entry
      oneOf:
      - $ref: '#/components/schemas/EntryV2TimeRunning'
      - $ref: '#/components/schemas/EntryV2TimeStopped'
      - $ref: '#/components/schemas/EntryV2TimeManual'
    ApiErrors:
      properties:
        type:
          description: Unique identifier of the error
          type: string
          examples:
          - General
        message:
          description: Textual error description
          type: string
          examples:
          - The requested resource could not be found.
        details:
          description: Additional error details if necessary
          type:
          - object
          - 'null'
          examples:
          - null
        path:
          type:
          - string
          - 'null'
      type: object
    EntryV2TimeStopped:
      title: Stopped Clock Entry
      allOf:
      - $ref: '#/components/schemas/EntryV2TimeBase'
      - required:
        - billable
        - time_until
        - duration
        - clocked
        - time_clocked_since
        properties:
          billable:
            $ref: '#/components/schemas/ApiEntriesV2_Billability'
          time_until:
            title: End date and time
            type: string
            format: date-time
            examples:
            - '2023-02-28T00:00:00Z'
          duration:
            title: Duration in seconds
            type: integer
            format: int64
          time_clocked_since:
            type: string
            format: date-time
            examples:
            - '2023-02-28T00:00:00Z'
          clocked:
            type: boolean
            enum:
            - true
        type: object
    ClockStartV2:
      required:
      - running
      - stopped
      - current_time
      - stopped_has_been_truncated
      properties:
        running:
          $ref: '#/components/schemas/EntryV2TimeRunning'
        stopped:
          title: Classified as a manual entry when the clock was stopped at zero duration
          type: object
          oneOf:
          - $ref: '#/components/schemas/EntryV2TimeStopped'
          - $ref: '#/components/schemas/EntryV2TimeManual'
          - type: 'null'
        current_time:
          type: string
          format: date-time
          x-precision: millisecond
          examples:
          - '2023-02-28T00:00:00.000Z'
        stopped_has_been_truncated:
          title: Stopped entry has been shortened in order to comply with maximum duration of 24h
          type: boolean
        additional_message:
          title: Warning shown when the started entry deviates from the request
          required:
          - text
          - type
          properties:
            text:
              type: string
            type:
              type: string
              examples:
              - warn
          type: object
        deleted_entries_ids:
          title: Ids of the time entries deleted while resolving overlaps, only present when "clear_overlaps" was requested
          type: array
          items:
            type: integer
            format: int64
        truncated_entries:
          title: Time entries shortened while resolving overlaps, only present when "clear_overlaps" was requested
          type: array
          items:
            $ref: '#/components/schemas/EntryV2Time'
      type: object
    Billable:
      title: Billable
      description: 'Possible values:

        - `0`: NotBillable

        - `1`: Billable

        - `2`: Billed

        - `12`: BillableOrBilled'
      type: integer
      enum:
      - 0
      - 1
      - 2
      - 12
      x-enumNames:
      - NotBillable
      - Billable
      - Billed
      - BillableOrBilled
    ClockV2:
      required:
      - running
      - stopped
      - current_time
      properties:
        running:
          oneOf:
          - $ref: '#/components/schemas/EntryV2TimeRunning'
          - type: 'null'
          type: object
        stopped:
          oneOf:
          - $ref: '#/components/schemas/EntryV2TimeStopped'
          - type: 'null'
          type: object
        current_time:
          type: string
          format: date-time
          x-precision: millisecond
          examples:
          - '2023-02-28T00:00:00.000Z'
      type: object
    EntryV2TimeManual:
      title: Manual Time Entry
      allOf:
      - $ref: '#/components/schemas/EntryV2TimeBase'
      - required:
        - billable
        - time_until
        - duration
        - clocked
        properties:
          billable:
            $ref: '#/components/schemas/ApiEntriesV2_Billability'
          time_until:
            title: End date and time
            type: string
            format: date-time
            examples:
            - '2023-02-28T00:00:00Z'
          duration:
            title: Duration in seconds
            type: integer
            format: int64
          clocked:
            type: boolean
            enum:
            - false
        type: object
    ClockStopV2:
      required:
      - running
      - stopped
      - current_time
      - stopped_has_been_truncated
      properties:
        running:
          oneOf:
          - $ref: '#/components/schemas/EntryV2TimeRunning'
          - type: 'null'
          type: object
        stopped:
          title: Classified as a manual entry when the clock was stopped at zero duration
          type: object
          oneOf:
          - $ref: '#/components/schemas/EntryV2TimeStopped'
          - $ref: '#/components/schemas/EntryV2TimeManual'
        current_time:
          type: string
          format: date-time
          x-precision: millisecond
          examples:
          - '2023-02-28T00:00:00.000Z'
        stopped_has_been_truncated:
          title: Stopped entry has been shortened in order to comply with maximum duration of 24h
          type: boolean
      type: object
    GeneralErrors:
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiErrors'
      type: object
    EntryV2TimeBase:
      title: Time Entry (shared fields)
      required:
      - id
      - customers_id
      - projects_id
      - subprojects_id
      - users_id
      - texts_id
      - text
      - time_since
      - time_insert
      - time_last_change
      - test_data
      - type
      - services_id
      - time_last_change_work_time
      - time_clocked_since
      - clocked_offline
      properties:
        id:
          title: ID
          type: integer
          format: int64
          examples:
          - 10
        customers_id:
          title: Customer's ID
          type: integer
          format: int64
          examples:
          - 10
        projects_id:
          title: Project's ID
          type:
          - integer
          - 'null'
          format: int64
        subprojects_id:
          title: Subproject's ID
          type:
          - integer
          - 'null'
          format: int64
        users_id:
          title: User's ID
          type: integer
          format: int64
        texts_id:
          title: Entry text's ID
          type:
          - integer
          - 'null'
          format: int64
        text:
          title: Description
          description: Only if enhanced_list=true
          type:
          - string
          - 'null'
        time_since:
          title: Start date and time
          type: string
          format: date-time
          examples:
          - '2023-02-28T00:00:00Z'
        time_insert:
          title: Insertion date and time
          type: string
          format: date-time
          examples:
          - '2023-02-28T00:00:00Z'
        time_last_change:
          title: Modification date and time
          type: string
          format: date-time
          examples:
          - '2023-02-28T00:00:00Z'
        test_data:
          title: is a test dataset?
          type: boolean
        customers_name:
          title: Customer's name
          description: Only if enhanced_list=true
          type: string
          examples:
          - Hotel Bergblick
        projects_name:
          title: Project's name
          description: Only if enhanced_list=true
          type:
          - string
          - 'null'
          examples:
          - Publicity campaign
        subprojects_name:
          title: Subproject's name
          description: Only if enhanced_list=true
          type:
          - string
          - 'null'
          examples:
          - Social media ads
        users_name:
          title: User's name
          description: Only if enhanced_list=true
          type: string
          examples:
          - Max Mustermann
        revenue:
          title: Revenue
          description: Only with necessary access rights and if enhanced_list=true
          type: number
          examples:
          - 999.9
        type:
          title: Type
          description: Entry type – discriminates the EntryV2 union. See EntryType.
          allOf:
          - $ref: '#/components/schemas/ApiEntriesV2_EntryType'
          enum:
          - 1
        services_id:
          title: Service's ID
          type: integer
          format: int64
        time_last_change_work_time:
          type: string
          format: date-time
          examples:
          - '2023-02-28T00:00:00Z'
        time_clocked_since:
          type:
          - string
          - 'null'
          format: date-time
          examples:
          - '2023-02-28T00:00:00Z'
        clocked_offline:
          type: boolean
        hourly_rate:
          description: Only with necessary access rights and if enhanced_list=true
          type: number
          examples:
          - 99.99
        services_name:
          title: Service's name
          description: Only if enhanced_list=true
          type: string
          examples:
          - SEO service
      type: object
    ApiEntriesV2_Billability:
      title: Billability
      description: 'Possible values:

        - `-1`: NotAvailable

        - `0`: NotBillable

        - `1`: Billable

        - `2`: Billed'
      type: integer
      enum:
      - -1
      - 0
      - 1
      - 2
      x-enumNames:
      - NotAvailable
      - NotBillable
      - Billable
      - Billed
    ClockDurationV2:
      title: Edit clocked duration response
      required:
      - updated
      - running
      - overlapping_correction
      - current_time
      properties:
        updated:
          $ref: '#/components/schemas/EntryV2Time'
        running:
          oneOf:
          - $ref: '#/components/schemas/EntryV2TimeRunning'
          - type: 'null'
          type: object
        overlapping_correction:
          required:
          - overlapping
          - overlapping_free_time_since
          - truncate_previous_entry
          properties:
            overlapping:
              type: boolean
              examples:
              - true
            overlapping_free_time_since:
              type:
              - string
              - 'null'
              format: date-time
              examples:
              - '2023-02-28T00:00:00Z'
            truncate_previous_entry:
              type:
              - integer
              - 'null'
              format: int64
              examples:
              - 1
          type:
          - object
          - 'null'
        current_time:
          type: string
          format: date-time
          x-precision: millisecond
          examples:
          - '2023-02-28T00:00:00.000Z'
      type: object
    ApiEntriesV2_EntryType:
      title: Entry type
      description: 'Possible values:

        - `1`: Time

        - `2`: LumpsumValue

        - `3`: LumpsumService'
      type: integer
      enum:
      - 1
      - 2
      - 3
      x-enumNames:
      - Time
      - LumpsumValue
      - LumpsumService
  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)