How to Integrate Retool with Teamwork

Teamwork authenticates API requests using an API token associated with your user account. To generate one, sign in to your Teamwork account and click your profile avatar in the top-right corner of the screen. Select 'Edit My Details' or 'Profile' from the dropdown. In your profile settings page, look for the 'API' tab or scroll down to find the 'API Tokens' section. Click 'Show your tokens' or 'Generate new API token'. Teamwork will display your API token — it is a long alphanumeric string. Copy it immediately and store it somewhere safe. Note that Teamwork API tokens are user-scoped, meaning the token has the same project and resource access as the account that generated it. For a cross-project portfolio dashboard, generate the API token from an admin account that has access to all client projects. If your Teamwork organization uses OAuth for integrations, you can alternatively set up an OAuth application in Teamwork's app settings — but for internal Retool dashboards, the API token approach is simpler and sufficient. Teamwork uses HTTP Basic authentication where the API token is used as the username and the letter 'x' is used as the password (this is a Teamwork-specific convention — the password field is ignored and 'x' is just a placeholder).

In Retool, navigate to the Resources tab from the left sidebar of your organization homepage. Click '+ Create new', scroll through the connector list, and select 'REST API'. On the configuration screen, set the Name to 'Teamwork API'. Set the Base URL to your Teamwork site URL in the format https://yourcompany.teamwork.com — replace yourcompany with your actual Teamwork subdomain. For Authentication, select 'Basic auth' from the dropdown. In the Username field, paste your Teamwork API token. In the Password field, type the letter x — this is required by Teamwork's API authentication convention but the value is ignored server-side. Add a header with key Content-Type and value application/json. Click 'Test connection' — if Retool can reach your Teamwork site and the API token is valid, the test should succeed. Click 'Save resource'. All queries made through this resource are proxied server-side by Retool, so the API token is never transmitted to browser clients. Note that Teamwork API responses return JSON by default, so you do not need a separate Accept header. If your Teamwork site uses a custom domain instead of the .teamwork.com subdomain, use that custom domain as the Base URL instead.

Open a Retool app and navigate to the Code panel at the bottom. Click '+ New query', select your Teamwork API resource, and name the query getProjects. Set the Method to GET and the URL path to /projects.json. Teamwork's API uses a .json suffix on endpoint paths to specify JSON format — this is a legacy convention but still required. Add URL parameters to control the response: set status to active to show only active projects (options: active, archived, current, late, upcoming), set orderBy to lastUpdated and orderMode to desc to see recently updated projects first, and set pageSize to 100 to maximize records per page. Click 'Run query'. Teamwork returns a projects array where each project has fields including id, name, description, company (nested object with name and id), status, created-on, last-changed-on, startDate, endDate, and subStatus. Note that Teamwork uses hyphenated field names (last-changed-on) rather than camelCase or snake_case — access them in JavaScript with bracket notation (project['last-changed-on']). Create a transformer on this query that flattens the company name out of the nested object and formats dates for display. Bind the transformed output to a Table component to show all active projects in a sortable list.

1// Transformer: flatten Teamwork projects with company names
2const projects = data.projects || [];
3return projects.map(p => ({
4  id: p.id,
5  name: p.name,
6  company: p['company']?.name || 'Internal',
7  company_id: p['company']?.id,
8  status: p.status || 'active',
9  sub_status: p['sub-status'] || '',
10  start_date: p.startDate || 'Not set',
11  end_date: p.endDate || 'No deadline',
12  last_updated: p['last-changed-on'] ? new Date(p['last-changed-on']).toLocaleDateString() : 'N/A'
13}));

With a project list displayed, build detail queries that run when a project is selected. Create a query named getMilestones with Method GET and path /projects/{{ projectsTable.selectedRow.id }}/milestones.json. Add parameters: set status to all (to show both completed and incomplete milestones), and order to deadline-asc to see upcoming deadlines first. Run after clicking a project row. Teamwork returns a milestones array where each milestone has id, title, deadline, completed (boolean), completed-on, and responsible-party-ids. Create a separate query named getTimeEntries with path /projects/{{ projectsTable.selectedRow.id }}/time_entries.json. Add parameters: set fromDate and toDate using a Retool DateRangePicker component to filter by billing period, and set billableType to billable to show only billable hours (or all for all entries). The time entries response includes hours, minutes, person-first-name, person-last-name, date, and isbillable fields. Create a JavaScript query named projectSummary that combines milestone and time data to produce summary statistics: total milestones, completed milestones, completion percentage, total hours logged (converting hours and minutes fields), and total billable hours. Display summary stats in Retool Stat components above the detail Tables.

1// Transformer: calculate project summary from milestones and time entries
2const milestones = getMilestones.data?.milestones || [];
3const timeEntries = getTimeEntries.data?.['time-entries'] || [];
4
5const totalMilestones = milestones.length;
6const completedMilestones = milestones.filter(m => m.completed === true).length;
7const completionRate = totalMilestones > 0
8  ? Math.round((completedMilestones / totalMilestones) * 100)
9  : 0;
10
11const totalHours = timeEntries.reduce((sum, t) => {
12  return sum + (parseInt(t.hours) || 0) + (parseInt(t.minutes) || 0) / 60;
13}, 0);
14
15const billableHours = timeEntries
16  .filter(t => t.isbillable === '1')
17  .reduce((sum, t) => sum + (parseInt(t.hours) || 0) + (parseInt(t.minutes) || 0) / 60, 0);
18
19return {
20  total_milestones: totalMilestones,
21  completed_milestones: completedMilestones,
22  completion_rate: `${completionRate}%`,
23  total_hours: totalHours.toFixed(1),
24  billable_hours: billableHours.toFixed(1),
25  next_deadline: milestones
26    .filter(m => !m.completed && m.deadline)
27    .sort((a, b) => new Date(a.deadline) - new Date(b.deadline))[0]?.deadline || 'None'
28};

A key capability of the cross-client dashboard is identifying projects that are at risk before they become problems. Create a query named getAllMilestones with Method GET and path /milestones.json (the root milestones endpoint, not per-project). Add parameters: set status to incomplete to fetch only outstanding milestones across all projects, and set getProgress to true to include the project context with each milestone. This endpoint returns milestones across your entire Teamwork site — exactly what you need for a portfolio-level risk view. Create a JavaScript query named atRiskProjects that processes the all-milestones response to identify projects with overdue milestones. Calculate days overdue for each milestone where the deadline is in the past and completed is false. Group by project and count overdue milestones per project. Combine this with the time budget data from a separate query if available. Sort by number of overdue milestones descending. Display the results in a Table with a red badge for projects with any overdue milestones and yellow for projects with milestones due within 7 days. Add an event handler on this Table's Row Click that sets the selected project in the main projects Table, triggering the full project detail view. For teams managing complex multi-client portfolios with cross-system billing integrations and automated client reporting, RapidDev's team can help design the complete Retool workflow.

1// Identify at-risk and overdue milestones across all projects
2const milestones = getAllMilestones.data?.milestones || [];
3const today = new Date();
4
5const enriched = milestones.map(m => {
6  const deadline = m.deadline ? new Date(m.deadline) : null;
7  const daysUntilDue = deadline ? Math.ceil((deadline - today) / (1000 * 60 * 60 * 24)) : null;
8  return {
9    milestone_title: m.title,
10    project_name: m['project-name'] || 'Unknown Project',
11    project_id: m['project-id'],
12    deadline: m.deadline || 'No deadline',
13    days_until_due: daysUntilDue,
14    risk_level: daysUntilDue === null ? 'Unknown'
15      : daysUntilDue < 0 ? 'Overdue'
16      : daysUntilDue <= 7 ? 'At Risk'
17      : 'On Track'
18  };
19});
20
21return enriched.sort((a, b) => {
22  const order = { 'Overdue': 0, 'At Risk': 1, 'On Track': 2, 'Unknown': 3 };
23  return order[a.risk_level] - order[b.risk_level];
24});