AppMatic Tech builds WHOOP API integrations that pull Recovery, Strain, Sleep, and Workout data through WHOOP's v2 REST API, OAuth 2.0, and signed webhooks into Node.js or Laravel back ends and Swift, Kotlin, or Flutter apps. AppMatic Tech is based in Ahmedabad, India, with 330+ products shipped and six BLE device integrations.
WHOOP is the reference product for subscription wearables. The WHOOP 5.0 and WHOOP MG bands, launched on May 8, 2025, are screenless, last 14 days per charge, and work only with an active membership. For coaching apps, corporate wellness platforms, team performance dashboards, and AI assistants, WHOOP members are an audience that already pays for physiological data and wants to use it elsewhere. This guide covers what the WHOOP API exposes, what it does not, and how to build an integration that stays reliable after launch.
Key takeaways
A WHOOP integration is an OAuth, webhook, and data-modelling project.
| Point | Detail |
|---|---|
| Current version | WHOOP API v2; v1 webhooks have been removed |
| Data available | Recovery, cycles (Strain), Sleep, Workouts, profile, body measurements |
| Not available | No documented endpoints for raw heart rate streams, ECG traces, or Blood Pressure Insights |
| Rate limits | 100 requests per minute and 10,000 per day, raisable on request |
| User limits | Sandbox 10, Build 100, Growth 1,000, Scale 5,000, Production unlimited |
| Webhooks | IDs only, HMAC-SHA256 signed, 5 retries over about 1 hour |
| Data model | Cycles follow the sleep-wake rhythm, not calendar days |
What WHOOP hardware and membership does the API sit on?
Every WHOOP API user is a WHOOP member, because the band does not work without a membership. That shapes the audience: engaged, paying users who check their data daily.
| Membership | Annual price (US) | Hardware | Features relevant to integrations |
|---|---|---|---|
| WHOOP One | $199 | WHOOP 5.0 | Strain, Recovery, Sleep, VO2 Max, heart rate zones, steps |
| WHOOP Peak | $239 | WHOOP 5.0 | Adds Health Monitor, Stress Monitor, and WHOOP Age |
| WHOOP Life | $359 | WHOOP MG | Adds the ECG Heart Screener and Blood Pressure Insights |
Both bands are rated at 14 days of battery and work with iOS and Android. The membership tier changes what the WHOOP app shows, but an API integration should be designed around the scored data the API documents, which is the same shape across tiers.
What data can an app read from the WHOOP API?
The v2 API exposes six user-data scopes, plus an offline scope for refresh tokens.
| Scope | Endpoints | Key fields |
|---|---|---|
read:recovery | GET /v2/recovery, GET /v2/cycle/{cycleId}/recovery | recovery_score, resting_heart_rate, hrv_rmssd_milli, spo2_percentage, skin_temp_celsius, user_calibrating |
read:cycles | GET /v2/cycle, GET /v2/cycle/{cycleId} | strain, kilojoule, average_heart_rate, max_heart_rate |
read:sleep | GET /v2/activity/sleep, GET /v2/activity/sleep/{sleepId} | stage_summary, sleep_needed, respiratory_rate, sleep_performance_percentage, sleep_consistency_percentage, sleep_efficiency_percentage |
read:workout | GET /v2/activity/workout, GET /v2/activity/workout/{workoutId} | strain, average_heart_rate, max_heart_rate, kilojoule, distance_meter, zone_durations |
read:profile | GET /v2/user/profile/basic | Name and email |
read:body_measurement | GET /v2/user/measurement/body | Height, weight, and max heart rate |
Collection endpoints are paginated with start, end, limit, and nextToken. A DELETE /v2/user/access endpoint revokes the app's access when a user disconnects, which every integration should call on account deletion.
WHOOP describes Recovery as a 0 to 100% score calculated from the previous day's measurements and sleep, using resting heart rate, heart rate variability, respiratory rate, sleep duration and quality, skin temperature, and blood oxygen. Strain is a non-linear 0 to 21 scale based on the Borg Scale of Perceived Exertion.
A separate Trusted Partner API, authenticated with client credentials, covers healthcare partner integrations such as service requests and lab requisitions. It is not part of the standard developer flow.
What data does the WHOOP API not provide?
The v2 API reference documents scored summaries, not sensor streams. It lists no endpoints for:
- Continuous heart rate samples at second-level resolution.
- ECG traces from the WHOOP MG Heart Screener.
- Blood Pressure Insights estimates.
- Journal entries, the behaviour logs members record in the WHOOP app.
The missing raw data matters at the scoping stage. A product that needs raw beat-to-beat data for research or custom algorithms cannot get it from WHOOP and should plan for a device with an open data interface, or its own hardware, as covered in how to build a screenless fitness tracker app.
Pro tip: Build product features around WHOOP's scores, not around recomputing them. Members trust the WHOOP Recovery number they see every morning, and a third-party app that shows a different "recovery" from the same band creates support tickets, not value.
How does WHOOP OAuth 2.0 work?
WHOOP uses the OAuth 2.0 authorization code flow.
- Create the app in the WHOOP Developer Dashboard, register redirect URLs and scopes, and receive a client ID and client secret.
- Send the user to
https://api.prod.whoop.com/oauth/oauth2/authwith the requested scopes. Includeofflineto receive a refresh token. - Exchange the code at
https://api.prod.whoop.com/oauth/oauth2/tokenfrom the back end, never from the mobile app, so the client secret stays on the server. - Call the API with the access token as a Bearer token. Access tokens are short-lived, and
expires_ingives the lifetime in seconds. - Refresh and rotate. Each refresh invalidates the previous refresh token, so the back end must store the new refresh token from every response atomically.
Refresh rotation is the most common cause of silent disconnections. If two workers refresh the same user's token at once, one of them stores a token that is already invalid. AppMatic Tech serialises refreshes per user with a lock, so only one refresh can run at a time.
How do WHOOP webhooks work?
WHOOP webhooks notify an app that data changed. They do not carry the data.
| Item | Detail |
|---|---|
| Events | recovery.updated, recovery.deleted, sleep.updated, sleep.deleted, workout.updated, workout.deleted |
| Payload | user_id, id (a UUID in v2), type, trace_id |
| Recovery IDs | For v2 recovery events, id is the UUID of the associated sleep |
| Signature | X-WHOOP-Signature and X-WHOOP-Signature-Timestamp headers; HMAC-SHA256 of the timestamp plus raw body, keyed with the client secret, base64-encoded |
| Retries | 5 retries over about 1 hour on any non-2XX response or timeout |
| Duplicates | trace_id identifies repeat deliveries |
The safe handling pattern:
- Verify the signature against the raw request body before parsing it.
- Reject stale timestamps to block replays.
- Return a 2XX response immediately and push the event onto a queue.
- Let a worker de-duplicate by
trace_id, fetch the object from the API, and upsert it. - Run a reconciliation job that re-fetches recent cycles, because WHOOP states that webhooks can be missed.
What are the WHOOP API rate limits and approval tiers?
WHOOP sets two separate limits: request volume and connected members.
Request limits. The defaults are 100 requests per minute and 10,000 requests per day. WHOOP raises them on request through the Developer Dashboard.
Member limits. Apps earn capacity one tier at a time:
| Tier | Connected members | Requirement to request the next tier |
|---|---|---|
| Sandbox | 10 | Can request Build at any time |
| Build | 100 | At least 50 members connected |
| Growth | 1,000 | At least 500 members connected |
| Scale | 5,000 | At least 2,500 members connected |
| Production | Unlimited | Not applicable |
Before any request, the app must follow the WHOOP API Terms of Use and the Design and Brand Guidelines, be tested with at least one WHOOP member, and carry an accurate app name, contact email, and privacy policy URL. WHOOP reviews requests manually, rejects vague answers, and may disable apps whose developers contact WHOOP employees outside the Developer Dashboard.
The tier system makes launch planning concrete. A product that expects 3,000 WHOOP users at launch needs to reach Scale first, which means growing through Build and Growth during a beta. AppMatic Tech schedules that ramp into the release plan rather than discovering it in launch week.
How should WHOOP data be modelled?
Three WHOOP concepts break naive data models.
- Cycles, not days
- WHOOP references activity in Physiological Cycles that follow the sleep-wake rhythm rather than midnight-to-midnight days. The current cycle has no end time until it closes, so a daily chart must map cycles to dates deliberately.
- Time zone offsets
- Each cycle stores a
timezone_offsetin W3C format, such as-05:00. Travelling users produce cycles in different offsets, so storage should be in UTC with the offset kept for display. - Score states
- Records carry a
score_state. OnlySCOREDrecords have a usable score; any other state means "not ready", and the app should show a pending state rather than a zero. - Calibration
- Recovery records include
user_calibrating, which is true while WHOOP builds a new member's baselines. Trends from that period should be labelled.
Sleep and workout IDs are UUIDs in v2. Teams migrating from v1 can map old integer IDs with the activity-mapping endpoint.
How should a WHOOP integration be architected?
AppMatic Tech's reference architecture for a WHOOP integration:
- Mobile app opens WHOOP OAuth in a system browser and hands the authorization code to the back end.
- Back end (Node.js or Laravel) exchanges the code, stores tokens encrypted, and serialises refreshes per user.
- Webhook receiver verifies signatures, acknowledges within milliseconds, and queues events.
- Sync worker fetches changed objects, respects the 100-per-minute limit with a shared rate limiter, and upserts into the product's own model.
- Reconciliation job re-fetches the last few cycles for active users each night.
- Product layer reads only from the product's model, so WHOOP is one source among several, alongside the Google Health API for Fitbit Air, Apple HealthKit, and Health Connect.
The adapter approach, one module per data source mapped into one internal model, is the same one used in one app, many devices.
Which products benefit from a WHOOP integration?
- Coaching apps that adapt training load to the member's Recovery and Strain.
- Corporate wellness and insurance programmes that reward sleep and activity consistency, subject to consent and the privacy rules covered in when a wearable app becomes a medical device.
- Team and club dashboards that show squad readiness to coaches, with each athlete authorising access.
- Nutrition and recovery apps that combine sleep and strain with meal logging, such as a connected kitchen scale app.
- AI assistants that answer questions over a member's WHOOP history through an MCP server, after confirming the use is permitted under the WHOOP API Terms of Use. The MCP pattern is explained in what is an MCP server.
AI use deserves a contract check for every vendor. Oura's API agreement, for example, restricts how its data can be passed to large language models, as compared in wearable health data APIs compared.
How AppMatic Tech builds wearable data integrations
AppMatic Tech has shipped 330+ products since 2017, holds a 5.0 Clutch rating, and keeps an 83% client retention rate. The wearable and sensor work includes EYVA, a six-vital wellness device app taken over mid-development and shipped in eight months, and Trackwel, a Flutter BLE app shipped in 10 weeks with zero app-side BLE errors.
The full service is on the AppMatic Tech wearable app development page, and fitness-specific work is on the sports and fitness technology page. Scoping a WHOOP integration starts at contact@appmatictech.com or the contact page.
Sources
| Claim used in this article | Source |
|---|---|
| Endpoints, scopes, and score fields | WHOOP API reference |
OAuth URLs, offline scope, refresh token rotation | WHOOP, OAuth 2.0 |
| Webhook events, payload, signature, retries, reconciliation | WHOOP, Webhooks |
| Rate limits of 100 per minute and 10,000 per day | WHOOP, API rate limiting |
| Approval tiers and request rules | WHOOP, App approval |
Physiological Cycles and timezone_offset | WHOOP, Cycle |
| Recovery inputs and Strain scale | WHOOP 101 |
| v1 to v2 changes and UUID IDs | WHOOP, v1 to v2 migration |
| WHOOP 5.0 and MG launch, battery, membership tiers and prices | Wareable, WHOOP 5.0 vs WHOOP MG |
Frequently Asked Questions
- Does WHOOP have a public API?
- Yes. The WHOOP Developer Platform offers a v2 REST API that lets third-party apps read a WHOOP member's Recovery, Strain (cycles), Sleep, Workout, profile, and body measurement data after the member authorises the app through OAuth 2.0. Apps are created in the WHOOP Developer Dashboard and start on a Sandbox tier limited to 10 connected members.
- What are the WHOOP API rate limits?
- WHOOP's default API rate limits are 100 requests per minute and 10,000 requests per day per app. WHOOP can raise the limits on request through the Developer Dashboard, where the developer opens a rate limit increase request and explains why the higher limit is needed.
- How many users can a WHOOP API app have?
- WHOOP API apps move through approval tiers: Sandbox allows 10 connected members, Build 100, Growth 1,000, Scale 5,000, and Production unlimited. Apps request one tier at a time, and from Build onward an app needs at least 50% of the current tier's member limit connected before requesting the next tier.
- Do WHOOP webhooks include the data?
- No. WHOOP webhooks carry only the user ID, the object ID, the event type, and a trace ID, so the app must call the WHOOP API to fetch the current data. Webhooks are signed with HMAC-SHA256 using the app's client secret, are retried five times over about one hour on failure, and should be backed by a periodic reconciliation job.
- Can the WHOOP API return raw heart rate or ECG data?
- The WHOOP v2 API reference documents scored summaries, such as recovery score, HRV, resting heart rate, strain, sleep stages, and workout zones, and lists no endpoints for continuous raw heart rate samples, ECG traces, or Blood Pressure Insights. Products that need raw sensor streams need a device with an open data interface instead.