How to Integrate Retool with Fitbit API

Navigate to dev.fitbit.com and log in with your Fitbit account (create one if needed — it does not need to be a paid account). Click 'Register an App' to create a new application registration. Fill in the required fields: application name (your wellness program name), description, website URL (your internal tool URL or company website), and most importantly the OAuth 2.0 Application Type — select 'Server' for server-side applications (not 'Personal' which only accesses the registering user's data). Set the Callback URL to a URL you control where users will be redirected after authorization — for internal tools, this can be a Retool app URL or a simple endpoint you set up to capture the authorization code. Under Default Access Type, select 'Read Only' unless you need to write exercise logs or update goals. After saving, Fitbit provides your OAuth 2.0 Client ID and Client Secret. Copy both values. The key limitation to understand: each Fitbit user must individually visit Fitbit's authorization page, log in, and grant access to your application before you can query their data. The resulting access token (valid for 8 hours) and refresh token (valid for indefinite use) must be stored and managed per-user in your own database.

In Retool, navigate to the Resources tab and click 'Create New'. Select 'REST API' from the resource type list. Set the Base URL to 'https://api.fitbit.com'. Fitbit's API uses versioned endpoints — most current endpoints are under '/1/' or '/1.2/' as path prefixes. Under Authentication, select 'Bearer Token' and enter a placeholder or leave blank — for per-user token scenarios, you will pass the token in each query's headers individually by overriding the resource-level authorization. This is because each query targets a different user's token. Alternatively, configure the resource with a default token for a single-user integration. Under Headers, add 'Accept-Language: en_US' to get measurements in the units matching your locale, and 'Accept-Locale: en_US' for consistent formatting. Store your Fitbit client ID and secret in Retool Settings → Configuration Variables as 'FITBIT_CLIENT_ID' and 'FITBIT_CLIENT_SECRET' for the token refresh flow. Add 'FITBIT_ACCESS_TOKEN' as a configuration variable if you are building a single-user integration. Click 'Save Resource'.

1{
2  "Base URL": "https://api.fitbit.com",
3  "Headers": {
4    "Accept-Language": "en_US",
5    "Accept-Locale": "en_US",
6    "Content-Type": "application/json"
7  },
8  "Authentication": "Bearer Token",
9  "Note": "For multi-user wellness programs, pass each user's token in the Authorization header override per-query: Authorization: Bearer {user_token}"
10}

Create a query to retrieve daily activity data for a specific user. Set the method to GET. Fitbit's activity summary endpoint returns comprehensive daily stats for a given date. The path format is '/1/user/{user-id}/activities/date/{date}.json' where user-id is the Fitbit user's ID (use '-' as a shorthand for the authenticated user when using their own token). The date format is YYYY-MM-DD. In the query header override, add 'Authorization: Bearer {{ selectedParticipant.fitbit_token }}' — where selectedParticipant is a state variable or table row containing the participant's stored token. The response 'summary' object contains: steps, floors, caloriesOut, distances array (including 'total' distance), minutesSedentary, minutesLightlyActive, minutesFairlyActive, minutesVeryActive, and the activity goals. For a date range, use the activities time series endpoint: '/1/user/-/activities/steps/date/{start-date}/{end-date}.json' which returns an array of date-value pairs. Add a DateRangePicker to control the date range and bind start/end dates to the query parameters.

1// GET /1/user/-/activities/steps/date/{start}/{end}.json
2// Headers: Authorization: Bearer {{ participantSelect.value }}
3// (participantSelect.value should contain the user's access token)
4
5// For single-day summary:
6// GET /1/user/-/activities/date/{date}.json
7
8// Transformer: format step data for chart
9const stepsData = data && data['activities-steps']
10  ? data['activities-steps']
11  : [];
12
13const weeklyTotal = stepsData.reduce((sum, day) => sum + parseInt(day.value || 0), 0);
14const weeklyAvg = stepsData.length > 0
15  ? Math.round(weeklyTotal / stepsData.length)
16  : 0;
17
18return {
19  daily_data: stepsData.map(day => ({
20    date: day.dateTime,
21    steps: parseInt(day.value || 0),
22    goal_met: parseInt(day.value || 0) >= 10000
23  })),
24  weekly_total: weeklyTotal,
25  weekly_avg: weeklyAvg,
26  goal_achievement_rate: stepsData.length > 0
27    ? Math.round((stepsData.filter(d => parseInt(d.value) >= 10000).length / stepsData.length) * 100)
28    : 0
29};

Create a sleep data query using Fitbit's sleep log endpoint. Set the method to GET and the path to '/1.2/user/-/sleep/date/{date}.json' for a single night, or '/1.2/user/-/sleep/date/{start-date}/{end-date}.json' for a range (maximum 100 days per request). Include the per-user Authorization header override. The response includes a 'sleep' array of sleep sessions for the night, and a 'summary' object with totalMinutesAsleep, totalTimeInBed, and for Fitbit users with heart rate tracking, the 'stages' breakdown (deep, light, rem, wake minutes). Extract key sleep metrics from the summary: total sleep duration, time in bed vs. time asleep (sleep efficiency percentage), and stages breakdown percentages. For sleep consistency analysis, compare bedtime and wake time across multiple days and calculate the standard deviation to measure consistency. Add an Image or Chart component showing a sleep stage pie chart bound to the stages data from the summary.

1// GET /1.2/user/-/sleep/date/{start}/{end}.json
2// Headers: Authorization: Bearer {{ participantToken }}
3
4// Transformer: format sleep data with quality metrics
5const sleepList = data && data.sleep ? data.sleep : [];
6
7// Filter to main sleep sessions (exclude short naps)
8const mainSessions = sleepList.filter(s => s.isMainSleep);
9
10return mainSessions.map(session => {
11  const duration = session.minutesAsleep || 0;
12  const inBed = session.timeInBed || 0;
13  const efficiency = inBed > 0 ? Math.round((duration / inBed) * 100) : 0;
14  const stages = session.levels && session.levels.summary
15    ? session.levels.summary
16    : {};
17
18  return {
19    date: session.dateOfSleep,
20    bedtime: session.startTime
21      ? new Date(session.startTime).toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit' })
22      : 'Unknown',
23    wake_time: session.endTime
24      ? new Date(session.endTime).toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit' })
25      : 'Unknown',
26    duration_hours: Math.round(duration / 60 * 10) / 10,
27    efficiency_pct: efficiency,
28    deep_min: stages.deep ? stages.deep.minutes : null,
29    rem_min: stages.rem ? stages.rem.minutes : null,
30    light_min: stages.light ? stages.light.minutes : null,
31    wake_min: stages.wake ? stages.wake.minutes : null,
32    quality: duration >= 420 && efficiency >= 85 ? 'Good'
33      : duration >= 360 && efficiency >= 75 ? 'Fair'
34      : 'Needs Improvement'
35  };
36});

Assemble the complete wellness program dashboard by combining participant management with Fitbit data queries. Create a database query to load all enrolled program participants from your participants table (which should include their name, enrollment date, program goals, and stored Fitbit access token). Display participants in a Table component on the left panel. When a program manager selects a participant row, the right panel loads that participant's Fitbit data using their stored token — bind the token from the selectedRow to the Authorization header of your activity and sleep queries. Build aggregated views using JavaScript transformers: calculate each participant's 7-day step average, compare against their personal goal (stored in your database), and compute a goal achievement percentage. Add Stat components showing program-wide metrics: total participants, average team steps today, percentage meeting their weekly step goal. Use Retool's row background color feature to highlight participants below 50% of their goal in yellow. For programs with complex data privacy requirements or multi-source data joins, RapidDev's team can help architect and build your Retool wellness solution.

1// JavaScript query: aggregate program metrics across all participants
2const participants = getParticipants.data || [];
3const participantSteps = {};
4
5// Build lookup from per-participant step queries
6// In practice, load each participant's steps in a loop via Workflow
7// This transformer assumes steps data has been pre-fetched and stored
8
9return participants.map(p => {
10  const stepsData = participantSteps[p.fitbit_user_id] || {};
11  const weeklyAvg = stepsData.weekly_avg || 0;
12  const goal = p.daily_step_goal || 10000;
13  const achievement = goal > 0 ? Math.round((weeklyAvg / goal) * 100) : 0;
14
15  return {
16    participant_id: p.id,
17    name: p.full_name,
18    enrollment_date: new Date(p.enrolled_at).toLocaleDateString(),
19    daily_goal: goal,
20    weekly_avg_steps: weeklyAvg,
21    goal_achievement_pct: achievement,
22    status: achievement >= 100 ? 'exceeding'
23      : achievement >= 75 ? 'on_track'
24      : achievement >= 50 ? 'at_risk'
25      : 'needs_support',
26    last_sync: p.fitbit_last_sync
27      ? new Date(p.fitbit_last_sync).toLocaleDateString()
28      : 'Never'
29  };
30}).sort((a, b) => a.goal_achievement_pct - b.goal_achievement_pct);