Unofficial JavaScript/TypeScript SDK for Clockodo.
npm install clockodo
For the constructor arguments, you must get the user (email) and clockodo API key from the "My area" section of Clockodo's website.
import{Clockodo}from"clockodo";constclockodo=newClockodo({client: {// You need to add some information about yourself that will be// sent along every request,// see https://docs.clockodo.com/#section/Clockodo-REST-API/Client-identification// PLEASE NOTE: name + ";" + email must not be longer than 50 characters.name: "Your application/company",email: "technical-contact@your-company.com",},authentication: {user: "test-user@example.com",// You can get your API key from https://my.clockodo.com/en/users/editselfapiKey: "kjfdskj643fgnlksf343kdslm",},});client: Specify anameand anemailfor theX-Clockodo-External-Applicationheaderauthentication: Specify auserand anapiKeyto authenticate every requestbaseUrl: Points to the Clockodo API. Defaults tohttps://my.clockodo.com/api
You can update the configuration later like this:
clockodo.api.config({authentication: {/* ... */},});We provide methods for Clockodo endpoints and normalize payload keys automatically: query params and request bodies are mapped from camelCase to snake_case (deeply), response bodies are mapped from snake_case to camelCase (deeply), and empty query values (undefined, null, "") are omitted. You can find the implementation in src/lib/mappings.ts.
For any questions about the different properties please consult the official Clockodo API documentation.
Some constants are also available for import:
import{AbsenceStatus,AbsenceType,Billability,EntriesTextsMode,EntryType}from"clockodo";console.log(EntryType.Time);// 1console.log(EntryType.LumpsumValue);// 2console.log(EntryType.LumpsumService);// 3console.log(Billability.NotBillable);// 0console.log(Billability.Billable);// 1console.log(Billability.Billed);// 2Checkout models for more constants and TypeScript types.
Gets a selected absence by its ID.
awaitclockodo.getAbsence({id: 7});Gets a user's (readonly) access rights for customers and projects.
awaitclockodo.getUsersAccessCustomersProjects({usersId: 67325});Gets a user's (readonly) access rights for services.
awaitclockodo.getUsersAccessServices({usersId: 67325});Gets a list of absences in the provided year
awaitclockodo.getAbsences({year: 2018});Get currently running entry for the credentials attached to Clockodo object.
awaitclockodo.getClock();Get specific customer by ID
awaitclockodo.getCustomer({id: 777});Get all customers from all pages.
awaitclockodo.getCustomers();// orawaitclockodo.getCustomers({filter: {// Filter by active flagactive: true,},});Get all customers from a specific page.
awaitclockodo.getCustomersPage({page: 2});Get the number of active and inactive projects per customer.
awaitclockodo.getCustomersCountProjects();// orawaitclockodo.getCustomersCountProjects({customersId: [10,11]});Get an entry by its ID.
awaitclockodo.getEntry({id: 4});Splits all entries for a given user and day at midnight.
awaitclockodo.splitAllEntriesAtMidnight({day: "2026-02-17",usersId: 123,});Get all entries from all pages.
import{Billability}from"clockodo";awaitclockodo.getEntries({// timeSince and timeUntil are requiredtimeSince: "2017-08-18T00:00:00Z",timeUntil: "2018-02-09T00:00:00Z",filter: {// You can also add additional filters herebillable: Billability.Billed,},});Get all entries from a specific page
awaitclockodo.getEntriesPage({timeSince: "2017-08-18T00:00:00Z",timeUntil: "2018-02-09T00:00:00Z",page: 2,});Get a group of entries defined by your criteria.
awaitclockodo.getEntryGroups({timeSince: "2017-08-18T00:00:00Z",timeUntil: "2018-02-09T00:00:00Z",grouping: ["customersId","projectsId"],roundToMinutes: 15,});Retreive all descriptions (and no additional info) entered for time and lump sum entries from all pages.
awaitclockodo.getEntriesTexts({term: "meeting with client",mode: EntriesTextsMode.Add,});Retreive all descriptions from a specific page.
awaitclockodo.getEntriesTextsPage({term: "meeting with client",mode: EntriesTextsMode.Edit,page: 2,});Get a project by its ID.
awaitclockodo.getProject({id: 1985});Get all projects from all pages.
awaitclockodo.getProjects();// orawaitclockodo.getProjects({filter: {// Filter by a specific customer idcustomersId: 123,// Filter by active flagactive: true,},});Get all projects from a specific page.
awaitclockodo.getProjectsPage({page: 2});Get all project report rows from all pages.
awaitclockodo.getProjectsReports();Get project report rows from a specific page.
awaitclockodo.getProjectsReportsPage({page: 2});Get a subproject by its ID.
awaitclockodo.getSubproject({id: 11});Get all subprojects from all pages.
awaitclockodo.getSubprojects();Get all subprojects from a specific page.
awaitclockodo.getSubprojectsPage({page: 2});Get a service by its ID.
awaitclockodo.getService({id: 10});Get list of all services
awaitclockodo.getServices();Get a list of services from a specific page.
awaitclockodo.getServicesPage({page: 2});Get team by id.
awaitclockodo.getTeam({id: 10});Get list of all teams from all pages.
awaitclockodo.getTeams();Get all teams from a specific page.
awaitclockodo.getTeamsPage({page: 2});Get a lumpsum service by its ID.
awaitclockodo.getLumpSumService({id: 10});Get a list of all lumpsum services
awaitclockodo.getLumpSumServices();Get a list of lumpsum services from a specific page.
awaitclockodo.getLumpSumServicesPage({page: 2});Get a specific target hour period for a specific user by its ID (not the ID of the user)
awaitclockodo.getTargethoursRow({id: 1234});Get list of target hours for all users, with option to pass an object with an usersId to filter the history of target hours to a specific user.
awaitclockodo.getTargethours();// orawaitclockodo.getTargethours({usersId: 346923});Create a target hour period for a user.
import{TargethoursRowType}from"clockodo";awaitclockodo.addTargethour({usersId: 1,type: TargethoursRowType.Weekly,dateSince: "2023-02-28",dateUntil: null,compensationMonthly: 0,});Update a target hour period by ID.
awaitclockodo.editTargethour({id: 1234,type: TargethoursRowType.Weekly,dateSince: "2023-02-28",});Delete a target hour period by ID.
awaitclockodo.deleteTargethour({id: 1234});Get a co-worker by their ID.
awaitclockodo.getUser({id: 1263});Get list of users from all pages.
awaitclockodo.getUsers();Get all users from a specific page.
awaitclockodo.getUsersPage({page: 2});Get a surcharge model by ID.
awaitclockodo.getSurchargeModel({id: 7});Get all surcharge models.
awaitclockodo.getSurchargeModels();Get a report for a specific user and year.
awaitclockodo.getUserReport({usersId: 1263,year: 2017});Get an employee/user's report, which contains data such as hours worked and holidays taken.
awaitclockodo.getUserReports({year: 2017,type: 1});Gets all nonbusiness groups.
awaitclockodo.getNonbusinessGroups();Gets a nonbusiness group by ID.
awaitclockodo.getNonbusinessGroup({id: 123});Gets all nonbusiness days for a given year.
awaitclockodo.getNonbusinessDays({nonbusinessGroupId: 123,year: 2021,});Gets a nonbusiness day by ID.
awaitclockodo.getNonbusinessDay({id: 12,year: 2026});Gets user and company settings for the logged-in user.
awaitclockodo.getMe();Get subscription data.
awaitclockodo.getSubscription();Get list of access groups.
awaitclockodo.getAccessGroups();Get an access group by ID.
awaitclockodo.getAccessGroup({id: 1});Get customers and projects access for an access group.
awaitclockodo.getAccessGroupsCustomersProjects({accessGroupsId: 1});Get services access for an access group.
awaitclockodo.getAccessGroupsServices({accessGroupsId: 1});Get a user's access rights for customers and projects.
awaitclockodo.getIndividualUserAccessCustomersProjects({usersId: 67325});Get a user's access rights for services.
awaitclockodo.getIndividualUserAccessServices({usersId: 67325});Get overtime reduction rows, optionally filtered by user(s).
awaitclockodo.getOvertimeReductions();// orawaitclockodo.getOvertimeReductions({usersId: 17});Get an overtime reduction by ID.
awaitclockodo.getOvertimeReduction({id: 7});Get user nonbusiness days from a specific page.
awaitclockodo.getUsersNonbusinessDaysPage({page: 1});Get all user nonbusiness days (all pages).
awaitclockodo.getUsersNonbusinessDays();Get user nonbusiness groups from a specific page.
awaitclockodo.getUsersNonbusinessGroupsPage({page: 1});Get all user nonbusiness groups (all pages).
awaitclockodo.getUsersNonbusinessGroups();Get a user nonbusiness group by ID.
awaitclockodo.getUsersNonbusinessGroup({id: 1});Gets work times from a specific page.
awaitclockodo.getWorkTimesPage({usersId: 123,dateSince: "2026-02-01",dateUntil: "2026-02-07",page: 2,});Gets all work time pages for the given filter.
awaitclockodo.getWorkTimes({usersId: 123,dateSince: "2026-02-01",dateUntil: "2026-02-07",});Gets work time change requests from a specific page.
awaitclockodo.getWorkTimesChangeRequestsPage({usersId: 123,dateSince: "2026-02-01",dateUntil: "2026-02-07",page: 2,});Gets all work time change request pages for the given filter.
awaitclockodo.getWorkTimesChangeRequests({usersId: 123,dateSince: "2026-02-01",dateUntil: "2026-02-07",});Gets overtime carry rows.
awaitclockodo.getOvertimecarry({usersId: 17,year: 2028});Gets an overtime carry row by ID.
awaitclockodo.getOvertimecarryRow({id: 7});Gets holiday quota rows.
awaitclockodo.getHolidaysQuotas({usersId: 17,year: 2028});Gets a holiday quota row by ID.
awaitclockodo.getHolidaysQuota({id: 7});Gets holiday carryover rows.
awaitclockodo.getHolidaysCarryovers({usersId: 17,year: 2028});Gets a holiday carryover row by ID.
awaitclockodo.getHolidaysCarryover({id: 7});Default behavior adds an absence for the user attached to the credentials given to the clockodo object. To add the absence for another user you can use the usersId option if you have the permissions.
import{AbsenceType}from"clockodo";awaitclockodo.addAbsence({dateSince: "2017-08-18T00:00:00Z",dateUntil: "2018-02-09T00:00:00Z",type: AbsenceType.SpecialLeave,note: "elternzeit",usersId: 12321,});Adds a customer to the organization.
awaitclockodo.addCustomer({name: "Weyland-Yutani"});Create an access group (name required; optional user IDs for members).
awaitclockodo.addAccessGroup({name: "Support Team"});Adds a lumpsum service.
awaitclockodo.addLumpsumService({name: "Flat Rate Support",price: 99});Creates a nonbusiness group.
awaitclockodo.addNonbusinessGroup({name: "NRW",preset: ""});Creates a nonbusiness day.
awaitclockodo.addNonbusinessDay({nonbusinessGroupId: 2,type: "DISTINCT_ONCE",name: "Labor Day",});Create a user nonbusiness group.
awaitclockodo.addUsersNonbusinessGroup({usersId: 17,nonbusinessGroupsId: 1,dateSince: "2023-02-28",});Creates an overtime carry row.
awaitclockodo.addOvertimecarry({usersId: 17,year: 2028,hours: 8,note: "carryover",});Create an overtime reduction row.
awaitclockodo.addOvertimeReduction({usersId: 17,date: "2028-01-28",hours: 8,});Creates a holidays quota row.
awaitclockodo.addHolidaysQuota({usersId: 17,yearSince: 2028,count: 30,});Creates a holidays carryover row.
awaitclockodo.addHolidaysCarryover({usersId: 17,year: 2028,count: 5,});Creates an entry for either the user attached to the Clockodo instance or the passed in usersId. Depending on the type of entry different properties are required:
| Type of entry | Required properties |
|---|---|
| Manual time entry | customersId, servicesId, billable, timeSince, timeUntil |
| Lumpsum value entry | customersId, servicesId, billable, timeSince, lumpsum |
| Lumpsum service entry | customersId, lumpsumServicesAmount, lumpsumServicesId, billable, timeSince |
import{Billability}from"clockodo";awaitclockodo.addEntry({customersId: 1,servicesId: 2,billable: Billability.Billable,timeSince: "2018-10-01T00:00:00Z",timeUntil: "2018-10-01T03:00:00Z",});Creates a project for an existing customer.
awaitclockodo.addProject({name: "Clockodo Api Wrapper",customersId: 1});Create the next project interval for a project by ID.
awaitclockodo.createNextProjectInterval({id: 20});Creates a subproject for an existing project.
awaitclockodo.addSubproject({projectsId: 1,name: "SDK Migration"});Adds to the list of services offered by your organization.
awaitclockodo.addService({name: "Thinking"});Creates a new team under your organization.
awaitclockodo.addTeam({name: "Gold Team"});Creates new user in organization.
import{UserRole}from"clockodo";awaitclockodo.addUser({name: "Merkel",number: "08",email: "angela@eu.eu",role: UserRole.Owner,});Adds a surcharge model.
awaitclockodo.addSurchargeModel({name: "Night Shift",accumulation: true});Start a new running clockodo entry.
import{Billability}from"clockodo";awaitclockodo.startClock({customersId: 24,servicesId: 7,projectsId: 365,billable: Billability.Billable,});Creates a work time change request.
import{WorkTimeChangeRequestIntervalType}from"clockodo";awaitclockodo.addWorkTimesChangeRequest({date: "2026-02-17",usersId: 123,changes: [{type: WorkTimeChangeRequestIntervalType.Add,timeSince: "2026-02-17T08:00:00Z",timeUntil: "2026-02-17T12:00:00Z",},],});Approves a work time change request by ID.
awaitclockodo.approveWorkTimesChangeRequest({id: 17});Declines a work time change request by ID.
awaitclockodo.declineWorkTimesChangeRequest({id: 17});Changes the duration of an entry. Because the ID returned by clock methods is just the entry ID, and this function can only be used after an entry is finished, there seems to be no difference from using editEntry().
awaitclockodo.changeClockDuration({entriesId: 7082,duration: 540,durationBefore: 300,});Edit existing Clockodo absence.
awaitclockodo.editAbsence({id: 74,note: "I know what he did last summer"});Edit existing Clockodo customer.
awaitclockodo.editCustomer({id: 15,name: "The Mystery Gang"});Update an access group by ID.
awaitclockodo.editAccessGroup({id: 1,name: "Updated Name"});Update an access group's customer access.
import{AccessType,AccessValue}from"clockodo";awaitclockodo.editAccessGroupsCustomer({accessGroupsId: 1,id: 10,type: AccessType.Add,value: AccessValue.FullAccess,});Update an access group's general customers access.
import{AccessType,AccessValue}from"clockodo";awaitclockodo.editAccessGroupsCustomersGeneral({accessGroupsId: 1,type: AccessType.Add,value: AccessValue.FullAccess,});Update an access group's project access.
import{AccessProjectOrServiceValue,AccessType}from"clockodo";awaitclockodo.editAccessGroupsProject({accessGroupsId: 1,id: 5,type: AccessType.Add,value: AccessProjectOrServiceValue.FullAccess,});Update an access group's service access.
import{AccessProjectOrServiceValue,AccessType}from"clockodo";awaitclockodo.editAccessGroupsService({accessGroupsId: 1,id: 3,type: AccessType.Add,value: AccessProjectOrServiceValue.FullAccess,});Update an access group's general services access.
import{AccessType,AccessValue}from"clockodo";awaitclockodo.editAccessGroupsServicesGeneral({accessGroupsId: 1,type: AccessType.Add,value: AccessValue.FullAccess,});Update a user's customer access.
import{AccessType,AccessValue}from"clockodo";awaitclockodo.editIndividualUserAccessCustomer({usersId: 67325,id: 10,type: AccessType.Add,value: AccessValue.FullAccess,});Update a user's general customers access.
import{AccessType,AccessValue}from"clockodo";awaitclockodo.editIndividualUserAccessCustomersGeneral({usersId: 67325,type: AccessType.Add,value: AccessValue.FullAccess,});Update a user's project access.
import{AccessProjectOrServiceValue,AccessType}from"clockodo";awaitclockodo.editIndividualUserAccessProject({usersId: 67325,id: 5,type: AccessType.Add,value: AccessProjectOrServiceValue.FullAccess,});Update a user's service access.
import{AccessProjectOrServiceValue,AccessType}from"clockodo";awaitclockodo.editIndividualUserAccessService({usersId: 67325,id: 3,type: AccessType.Add,value: AccessProjectOrServiceValue.FullAccess,});Update a user's general services access.
import{AccessType,AccessValue}from"clockodo";awaitclockodo.editIndividualUserAccessServicesGeneral({usersId: 67325,type: AccessType.Add,value: AccessValue.FullAccess,});Edit an existing lumpsum service.
awaitclockodo.editLumpsumService({id: 15,name: "Updated Flat Rate"});Changes the values of a Clockodo entry. Unlike changeClockDuration(), editEntry() can seemingly mutate any of the accepted parameters even when the entry is running.
awaitclockodo.editEntry({id: 365,duration: 540});Allows for mass edit of entries based on a set of filters.
import{Billability}from"clockodo";awaitclockodo.editEntryGroup({timeSince: "2017-08-18T00:00:00Z",timeUntil: "2018-02-09T00:00:00Z",filter: {text: "Browsing Reddit",billable: Billability.NotBillable,},});Edit existing project.
awaitclockodo.editProject({id: 20,name: "Awesome new project"});Set a project's completion status.
awaitclockodo.completeProject({id: 20,completed: true});Set a project's billed status and billed amount.
awaitclockodo.setProjectBilled({id: 20,billed: true,billedMoney: 1234.5});Edit existing subproject.
awaitclockodo.editSubproject({id: 20,name: "SDK Migration Phase 2"});Set a subproject's completion status.
awaitclockodo.completeSubproject({id: 20,completed: true});Edit existing service.
awaitclockodo.editService({id: 23,name: "Room Service"});Edit existing team.
awaitclockodo.editTeam({id: 6324,name: "New Team Name"});Edit existing user.
awaitclockodo.editUser({id: 33,name: "Moalo Loco"});Edit an existing surcharge model.
awaitclockodo.editSurchargeModel({id: 365,name: "ABC"});Edits a nonbusiness group.
awaitclockodo.editNonbusinessGroup({id: 2,name: "Holidays"});Edits a nonbusiness day.
awaitclockodo.editNonbusinessDay({id: 2,name: "Holiday",type: "DISTINCT_RECURRING",});Update a user nonbusiness group by ID.
awaitclockodo.editUsersNonbusinessGroup({id: 1,name: "Updated Group"});Edits an overtime carry row.
awaitclockodo.editOvertimecarry({id: 2,hours: 8,note: "updated"});Update an overtime reduction by ID.
awaitclockodo.editOvertimeReduction({id: 2,hours: 4});Edits a holidays quota row.
awaitclockodo.editHolidaysQuota({id: 2,count: 25,note: "updated"});Edits a holidays carryover row.
awaitclockodo.editHolidaysCarryover({id: 2,count: 5,note: "updated"});Clear individual user access (customers/projects and services) for a user.
awaitclockodo.clearIndividualUserAccess({usersId: 67325});Delete an access group by ID.
awaitclockodo.deleteAccessGroup({id: 1});Deletes the customer.
awaitclockodo.deleteCustomer({id: 343});Deletes the project.
awaitclockodo.deleteProject({id: 8});Deletes the subproject.
awaitclockodo.deleteSubproject({id: 8});Deletes the service.
awaitclockodo.deleteService({id: 94});Deletes user.
awaitclockodo.deleteUser({id: 7});Deletes a surcharge model by ID.
awaitclockodo.deleteSurchargeModel({id: 31});Deletes absence (go figure).
awaitclockodo.deleteAbsence({id: 31});Deletes a single entry by ID
awaitclockodo.deleteEntry({id: 543512});Deletes a lumpsum service by ID.
awaitclockodo.deleteLumpsumService({id: 94});Deletes a team by ID
awaitclockodo.deleteTeam({id: 764});Deletes a nonbusiness group by ID.
awaitclockodo.deleteNonbusinessGroup({id: 31});Delete a user nonbusiness group by ID.
awaitclockodo.deleteUsersNonbusinessGroup({id: 1});Deletes a nonbusiness day by ID.
awaitclockodo.deleteNonbusinessDay({id: 31});Deletes an overtime carry row by ID.
awaitclockodo.deleteOvertimecarry({id: 31});Delete an overtime reduction by ID.
awaitclockodo.deleteOvertimeReduction({id: 31});Deletes a holidays quota row by ID.
awaitclockodo.deleteHolidaysQuota({id: 31});Deletes a holidays carryover row by ID.
awaitclockodo.deleteHolidaysCarryover({id: 31});Deletes one or more entries based on a series of filters that builds an "entry group".
awaitclockodo.deleteEntryGroup({timeSince: "2017-08-18T00:00:00Z",timeUntil: "2018-02-09T00:00:00Z",text: "chilin everyday",});Withdraws a work time change request by ID.
awaitclockodo.withdrawWorkTimesChangeRequest({id: 17});Creates a new clockodo account.
awaitclockodo.register({companiesName: "Acme Corporation",name: "Road Runner",email: "runner@acme.com",});Stops a running clock/entry.
awaitclockodo.stopClock({entriesId: 7082});awaitclockodo.stopClock({entriesId: 7082,usersId: 123});To run integration tests you need to create an .env by copying the .env.example and entering credentials of a dev-user, as you don't want to mess up your real clockodo data.
MIT
