.png)
WHOOP has built a reputation as one of the most data-rich consumer wearables on the market, particularly for recovery and strain metrics. Its proprietary scoring system, daily coaching, and focus on HRV-based readiness have made it a device of choice for athletes, clinical researchers, and increasingly for digital health builders who want physiological depth beyond step counts and generic activity.
The WHOOP API V2, introduced in July 2025, opens access to that data for developers. This post covers what the API actually exposes, how the integration works end-to-end, and what you need to understand before building on it.
Before getting into the integration specifics, it is worth understanding what WHOOP measures and why it matters for health applications.
WHOOP's core output is not raw sensor data. It is derived metrics: a Recovery Score (0-100%) that reflects how prepared the body is for strain, a Strain Score (0-21 on a logarithmic scale) that tracks cardiovascular load, and a Sleep Performance percentage that compares actual sleep against computed sleep need.
The underlying signals that power these scores include:
The combination of continuous overnight measurement and longitudinal scoring is what differentiates WHOOP data from most consumer wearables. The trade-off is that WHOOP is a passive strap with no GPS, no display, and no standalone workout-tracking interface, so some fields you might expect (workout distance, pace, altitude) are rarely populated because most users' GPS data comes from a separate device.
The WHOOP API V2 is organized around six data categories, each behind its own OAuth scope:
A few important points on scope and coverage:
Getting started requires creating an application in the WHOOP Developer Dashboard. You register your application details, define the redirect URLs you will use for OAuth callbacks, and select the scopes your application needs. The dashboard then provides a client ID and client secret.
Keep the client secret on your backend. It should never appear in client-side code, mobile apps, or version control.
Development access is capped at 10 WHOOP members. To support more users, you need to submit your application for approval through the dashboard. WHOOP asks for a working integration tested with at least one member, a privacy policy, accurate contact information, and compliance with design guidelines. There is no published timeline for review.
Authorization uses the OAuth 2.0 authorization-code flow. The user is redirected to WHOOP, logs in, and approves the scopes your application requested. WHOOP then redirects back to your registered callback URL with an authorization code, which you exchange server-side for an access token and a refresh token.
To maintain ongoing access after the initial session, you must include the offline scope in your authorization request. Without it, you do not receive a refresh token and cannot maintain access past the initial token expiry.
Token refresh requires care. When you refresh an access token, WHOOP replaces both the access token and the refresh token. Your application must store the new pair immediately. If two background workers attempt to refresh the same user's token simultaneously, one will succeed and the other will fail because the first refresh has already invalidated the previous token. Coordinate refresh attempts to avoid this.
Data is retrieved through REST endpoints. Each endpoint returns paginated responses using a next_token cursor. Receiving the first page does not mean you have retrieved the complete history. Implement pagination correctly, particularly during initial historical sync when you are retrieving months of data for a new user.
Rate limits apply per application: 100 requests per minute and 10,000 requests per day by default. At scale, these limits constrain how many users you can keep synchronized. As a rough example, fetching one endpoint per hour for 1,000 users generates 24,000 daily requests, already exceeding the default allowance before accounting for historical imports, retries, or additional data categories. You can request higher limits through the dashboard, but plan for this before you need it.
WHOOP provides webhooks for three data types: sleep, recovery, and workouts. Each supports both updated and deleted events. Webhooks carry event notifications and identifiers, not full records. When a webhook fires, your application fetches the relevant record by ID.
Webhook delivery is not guaranteed. Design your integration to handle duplicate events and to detect missed events through periodic reconciliation. Validate webhook signatures using your client secret. Note that webhooks are currently not available for Day Strain, cycles, or body measurements, so those require polling.
WHOOP's V2 recovery webhooks identify the associated sleep by UUID rather than cycle ID. If you are migrating an integration from V1, this is a change that requires updating your record-linking logic.
A few fields worth understanding in detail before you build:
Recovery records arrive after sleep is scored. They include the recovery score, HRV (in milliseconds, RMSSD), resting heart rate (in beats per minute), and optionally SpO2 and skin temperature. These are the fields most relevant for digital health applications focused on readiness, stress monitoring, or longitudinal physiological tracking.
Sleep records include start and end timestamps, duration in each sleep stage (in milliseconds), respiratory rate, sleep performance percentage, sleep efficiency, and consistency score. The sleep need computation, which determines sleep performance, accounts for the user's prior strain and historical patterns. Sleep records can also flag whether a record represents a nap versus a primary sleep session.
Workout records include Strain score, sport ID, and heart rate summaries. GPS-derived fields such as distance and elevation are present in the schema but are null for the vast majority of workouts, because WHOOP is a passive strap and most users record location data on a separate device. Build your handling around the expectation that these fields are null rather than the exception.
Cycle records provide Day Strain and cover the physiological cycle rather than a calendar day. The current in-progress cycle will have a start time and no end time. Cycles are the unit WHOOP uses to organize all recovery and strain data.
Physiological cycles versus calendar dates. Most health applications display data by date. WHOOP organizes it by cycle. A recovery score timestamped on a given day may reflect sleep that started the previous night. If you map cycle data onto calendar days without accounting for this, your users will see data assigned to the wrong day.
Rate limit planning. The default limits are tight for any application with more than a few hundred connected users. Plan your polling architecture early. Use webhooks wherever possible to reduce unnecessary API calls. Implement backoff on 429 responses. Request higher limits before you launch.
Historical sync volume. New users connecting their WHOOP account may have months or years of historical data. A full historical sync for a single user can require dozens of API requests across multiple endpoints and paginated responses. Run historical syncs as background jobs and track progress so they can be resumed if interrupted.
Score state handling. Pending and unscorable records need to be handled explicitly. A pending recovery score is not a zero score. Build your data model to represent these states and to handle subsequent updates when a pending record is later scored.
Token refresh coordination. If your platform runs multiple background workers and any of them handles token refresh, implement distributed locking or a centralized refresh service. Concurrent refresh attempts will result in one worker holding an invalid token and failing on the next API call.
The integration challenges above are ones that every team building on the WHOOP API has to solve: OAuth and token management, pagination, rate limit handling, webhook reliability, cycle-to-date mapping, HRV normalization, and score state logic.
At Thryve, WHOOP is one of 500+ connected wearables and health data sources on the platform. The integration layer handles authentication, token refresh, webhook processing, and historical sync across all connected devices. WHOOP data is normalized alongside data from Garmin, Oura, Apple Watch, and other sources, so the RMSSD-versus-SDNN distinction is resolved at the infrastructure layer rather than inside your application. You can find more details on our WHOOP integration page!
Partners receive a single normalized stream of wearable data through one API, without maintaining per-device polling logic, backfill windows, or the operational complexity of managing hundreds of device-specific integration behaviors.
If you are building a digital health product, a clinical research platform, or an insurance analytics application on wearable data and want to understand what a production-ready WHOOP integration looks like at scale, book a demo with Thryve.
Friedrich Lämmel is CEO of Thryve, the plug & play API to access and understand 24/7 health data from wearables and medical trackers. Prior to Thryve, he built eCommerce platforms with billions of turnover and worked and lived in several countries in Europe and beyond.
.png)
.png)