How to switch from one health data aggregator to another

Switching from one health data aggregator to another

You're moving your integration from one aggregator to another — say Terra to Junction (formerly Vital), Rook, or Spike, or any pairing among them. Here's the honest version up front: this is a real re-integration, not a config swap. Each aggregator has its own normalized schema, its own connect/widget flow, and its own webhook signatures, so you re-map fields, rewire your webhook handler, and — the biggest gotcha — your users must reconnect, because the grants and refresh tokens held by the old aggregator do not transfer to the new one. Plan to run both in parallel and migrate users in waves.

If you're still deciding which aggregator to land on, that comparison lives in Terra vs Vital and Terra alternatives — this page assumes you've picked the destination and covers the move itself.

Why teams switch aggregators

The trigger is usually one of these, and all of them shift over time — treat any specific claim as "as of 2026, verify current docs":

• Pricing / cost structure at scale. Per-connection or per-MAU costs differ between vendors, and what's cheapest at 1,000 users may not be at 100,000. Verify current pricing with each vendor directly.
• Provider and device coverage. Which wearables and which data types each aggregator supports differs. Coverage parity is per-provider and per-field — confirm both before committing.
• Reliability, latency, normalization quality, and support. Webhook latency, how cleanly each vendor normalizes data, and how responsive their support is all vary. Do not treat any vendor ranking as settled fact; these shift.

What actually changes

The move is real engineering work because the two aggregators are genuinely different products behind their "one API" marketing.

Back-fill depth is worth calling out separately: how far back you can pull historical data is set by each underlying provider, not by the aggregator you choose. Terra, for example, documents different per-provider caps (Garmin, Polar, and Coros each differ) — verify current limits. Switching aggregators does not raise those caps.

For the target's setup mechanics, see the Terra API integration guide; for the concept itself, what is a health data aggregator.

The migration, step by step

1. Confirm coverage parity. Verify the new aggregator covers every provider AND every specific data field you currently consume. Check per-provider and per-field — do not assume "supports Garmin" means the exact metric you rely on survives normalization.
2. Map the schemas. Build a field-by-field table from the old aggregator's normalized schema to the new one. Flag every dropped or renamed field, and confirm raw/passthrough availability if you depend on a provider-specific field.
3. Register any provider apps the new aggregator requires you to own. Some providers (e.g. Garmin, WHOOP, Fitbit) may still need your own developer credentials and approval even behind an aggregator. Submit these early — approvals take lead time. Verify per provider.
4. Stand up the new webhook endpoint in parallel. Deploy the new aggregator's endpoint alongside the old one and implement its signature verification and event model. Do not decommission the old path yet.
5. Wire user-identity reconciliation. Map the new aggregator's reference-id convention back to your user IDs so incoming events resolve to the right user.
6. Re-consent users in waves. Ship a reconnect prompt that deep-links into the new connect flow, explain why reconnection is needed, and migrate cohorts rather than doing a big-bang cutover. Track per-user state (old-connected / reconnected / failed) to target reminders.
7. Back-fill history on the new path. Pull historical data through the new aggregator within each provider's cap. Expect large ranges to arrive asynchronously in chunks; reconcile against the old path.
8. Dual-run, validate, then decommission. Compare old vs new data over a validation window, keep rollback available per cohort, and only turn down the old aggregator once reconnection rate and data continuity are confirmed.

Gotchas and how to keep users connected

• Connections do not transfer. This is the number-one way to silently lose users. OAuth grants and refresh tokens are bound to the old aggregator's app; the new path needs a fresh authorization from each user. Plan re-consent from day one — see keep users connected during a migration.
• Data gaps during the wave. Until a user reconnects, keep the old path flowing so their data doesn't stop. Dual-read both sources and reconcile.
• Dropped fields hide in the normalized schema. A unified schema can flatten or omit provider-specific fields. If your product logic reads one, confirm the new aggregator exposes it (raw passthrough if needed) before you cut over.
• Back-fill won't be deeper than the provider allows. Set expectations: you cannot restore more history than each provider permits, regardless of which aggregator you use.

How much effort is this, really

Budget for it as a full re-integration of your ingestion layer plus a user-facing reconnect campaign — not a weekend swap. The engineering (schema mapping, new webhook handling, identity reconciliation) is bounded and predictable; the reconnect rate is the variable that determines your timeline. Always confirm the destination aggregator's current schema, connect flow, webhook scheme, and per-provider back-fill caps against its live documentation before you commit, since all of these shift.