How to Integrate Retool with Time Doctor

Time Doctor supports two authentication approaches for API access: OAuth 2.0 with username/password for session tokens, and API tokens generated from the Time Doctor web application. For server-side Retool integrations, an API token is the most practical option as it does not expire on a fixed schedule and does not require a browser-based OAuth flow. In the Time Doctor web app, navigate to Settings (gear icon in the top right). Select Integrations from the settings menu. Scroll to find the API Tokens section (if available on your plan) or look for the Access Token section. Click Generate Token or Create Token. Give the token a descriptive name such as Retool Integration. Copy the generated token immediately — Time Doctor displays it only once in some versions. If your Time Doctor plan does not offer standalone API tokens in the UI, you can obtain a session token by calling the authentication endpoint directly. POST to https://api2.timedoctor.com/api/1.1/authorization with a JSON body containing { email: "your@email.com", password: "yourpassword", totpCode: "" } — the response returns an access token and a companyId. For production integrations, the API token approach is preferred over embedding credentials; if using the login endpoint, implement a Retool Workflow to refresh the session token periodically since session tokens may have shorter expiry windows. Note your company_id from the authentication response or from your Time Doctor account URL — it is required as a query parameter in most API endpoints.

In Retool, navigate to the Resources tab in the left sidebar and click Add Resource. Select REST API from the resource type list. Name the resource Time Doctor API. In the Base URL field, enter https://api2.timedoctor.com/api/1.1 — this is the Time Doctor API v1.1 base URL used for all data endpoints. In the URL Parameters section (not Headers — Time Doctor uses token as a query parameter, not an Authorization header), click Add Parameter. Set the parameter name to token and the value to {{ config.TIMEDOCTOR_TOKEN }}. This appends the token to every API request automatically. Create the configuration variable: navigate to Settings → Configuration Variables in Retool, click Add variable, name it TIMEDOCTOR_TOKEN, paste your API token as the value, and enable the secret toggle to prevent the token from being exposed in frontend context. Create a second configuration variable named TIMEDOCTOR_COMPANY_ID with your company's numeric ID. This will be referenced in query URL parameters rather than the global resource settings, since most Time Doctor endpoints require it as a query parameter named company. Click Save on the Resource. Test the connection by creating a quick GET query with Path set to /users and a URL Parameter company set to {{ retoolContext.configVars.TIMEDOCTOR_COMPANY_ID }} — this should return a list of users in your company.

Create a new query in Retool targeting your Time Doctor API resource to fetch worklogs — the core data type representing time worked. Set Method to GET and Path to /activity/worklog. In the URL Parameters section, add company with value {{ retoolContext.configVars.TIMEDOCTOR_COMPANY_ID }}. Add start_date with value {{ formatDate(dateRangePicker.value[0], 'YYYY-MM-DD') }} and end_date with value {{ formatDate(dateRangePicker.value[1], 'YYYY-MM-DD') }}. Add user_ids as an optional filter — leave blank to get data for all users, or reference a multi-select dropdown: {{ userSelect.value.join(',') }}. The worklogs endpoint returns an array of time entries. Each entry has a userId, workMode (online or offline), start time, and a length in seconds. Add a JavaScript transformer to aggregate these raw worklog entries by user and date, summing the duration to compute daily hours per user. Time Doctor also provides a summary endpoint at /activity/summary which returns pre-aggregated totals per user for a date range — this is more efficient for daily summary views. Test the worklogs query by setting a date range of the last 7 days and verifying that entries appear for your team members. The raw worklog data will show many short entries representing individual tracked work sessions.

1// JavaScript transformer: aggregate raw worklogs by user and date
2// Input: data = array of worklog entry objects from Time Doctor API
3const worklogs = data.worklog || data || [];
4
5// Group by userId + date
6const byUserDate = {};
7
8worklogs.forEach(entry => {
9  const userId = entry.userId || entry.user_id || '';
10  const date = entry.start
11    ? entry.start.substring(0, 10)  // Extract YYYY-MM-DD
12    : '';
13  const duration = parseInt(entry.length || entry.duration || 0); // seconds
14
15  const key = `${userId}_${date}`;
16  if (!byUserDate[key]) {
17    byUserDate[key] = {
18      user_id: userId,
19      date: date,
20      total_seconds: 0,
21      sessions: 0
22    };
23  }
24  byUserDate[key].total_seconds += duration;
25  byUserDate[key].sessions += 1;
26});
27
28// Convert to array with formatted hours
29return Object.values(byUserDate).map(entry => ({
30  user_id: entry.user_id,
31  date: entry.date,
32  sessions: entry.sessions,
33  total_seconds: entry.total_seconds,
34  hours_worked: (entry.total_seconds / 3600).toFixed(2),
35  hours_display: `${Math.floor(entry.total_seconds / 3600)}h ${Math.floor((entry.total_seconds % 3600) / 60)}m`
36}));

With worklog data available, build the team monitoring dashboard. First, fetch the user list by creating a second GET query to /users with the company parameter — this provides names to display alongside user IDs from the worklog data. Add a DateRangePicker at the top of the canvas set to last 7 days by default. Create a JavaScript query that joins the worklog aggregates with user names: use the user list from the users query as a lookup map, matching user_id to display names. Drag a Table component onto the canvas and bind it to the joined dataset. Configure the Table to show: User Name, Date, Hours Worked, and Sessions columns. Enable row grouping by User Name to create a collapsible view where each user's daily entries are nested under their name. Add a summary row showing per-user totals. Add Stat components at the top showing team-level totals: total hours logged across all users, average hours per user per day, and total number of active users (users with at least one session). Drag a Bar Chart component showing total hours per user for the period — this gives a visual comparison of individual contributions. Add a second Chart as a Line chart showing team-level total hours by day over the date range, making it easy to spot days with low attendance or unusually high overtime. Add a user filter dropdown bound to the users query data so managers can narrow the Table to specific team members.

1// JavaScript query: join worklog aggregates with user names
2// Assumes: getWorklogs.data = aggregated worklog array, getUsers.data = user list
3const worklogs = getWorklogs.data || [];
4const users = getUsers.data?.users || getUsers.data || [];
5
6// Build user lookup map
7const userMap = {};
8users.forEach(u => {
9  userMap[u.id || u.userId] = {
10    name: u.name || u.fullName || `User ${u.id}`,
11    email: u.email || ''
12  };
13});
14
15// Merge names into worklog records
16return worklogs.map(entry => ({
17  ...entry,
18  user_name: userMap[entry.user_id]?.name || `User ${entry.user_id}`,
19  user_email: userMap[entry.user_id]?.email || ''
20}));

Time Doctor tracks not just hours worked but also app and website usage, classifying each application as productive, unproductive, or neutral. Enrich the dashboard with this productivity data. Create a third GET query targeting /activity/computer-activity with the company and user_ids parameters and the same date range parameters. This endpoint returns app/website usage data per user, including the application name, URL (for websites), duration, and productivity classification set in your Time Doctor account. Add a JavaScript transformer to aggregate app usage by user and productivity category, computing a productive time percentage: (productive_seconds / total_seconds) * 100. Drag a second Table onto the canvas (consider placing it in a Tab component to keep the layout clean) to show app usage data. Include a User dropdown that filters the app usage Table to show data for the selected user. For each user row in the main Table, add an event handler on row click that sets the selected user for the app usage Tab, creating a drill-down workflow: click a user in the attendance Table → switch to the App Usage tab → see that user's app breakdown. For detailed per-session screenshot review, query /screenshots with a user_id and date to fetch screenshot metadata including timestamp and the screenshot URL, then display thumbnails in a Retool Image component or link to them from the Table.

1// JavaScript transformer: compute productivity scores from computer activity data
2const activity = data.computerActivity || data || [];
3
4// Group by user
5const byUser = {};
6activity.forEach(entry => {
7  const userId = entry.userId || '';
8  const duration = parseInt(entry.time || entry.duration || 0);
9  const productivity = entry.productivity || 'neutral'; // 'productive', 'unproductive', 'neutral'
10
11  if (!byUser[userId]) {
12    byUser[userId] = { user_id: userId, productive: 0, unproductive: 0, neutral: 0, total: 0 };
13  }
14  byUser[userId][productivity] += duration;
15  byUser[userId].total += duration;
16});
17
18return Object.values(byUser).map(u => ({
19  user_id: u.user_id,
20  total_seconds: u.total,
21  productive_seconds: u.productive,
22  unproductive_seconds: u.unproductive,
23  neutral_seconds: u.neutral,
24  productive_pct: u.total > 0 ? ((u.productive / u.total) * 100).toFixed(1) + '%' : '0%',
25  hours_productive: (u.productive / 3600).toFixed(2)
26}));