> ## Documentation Index
> Fetch the complete documentation index at: https://docs.saturday.fit/llms.txt
> Use this file to discover all available pages before exploring further.

# The Athlete Onboarding Journey

> Narrative walkthrough of what an athlete sees and what your code should do, step by step

This page is a narrative, written so a developer, or an AI assistant building your integration, can picture the whole athlete experience and know what to implement at each beat. The reference details live in [Athlete Onboarding](/guides/onboarding); this is the story.

## State machine

An athlete on your platform is always in exactly one of these states:

| State                       | What calculations return                                                                        | What moves them forward                     |
| --------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------- |
| **No profile**              | Widest bands, plus an onboarding invite. Trial clock not started.                               | Any single answered field                   |
| **Partial profile**         | Narrower bands; `missing_fields` shows what is left, most-impactful first. Trial clock running. | More answers, by any of the four mechanisms |
| **Complete, in trial**      | Exact numbers, for 30 days, within the daily call cap                                           | Subscribing                                 |
| **Complete, subscribed**    | Exact numbers, always                                                                           | Nothing left to do                          |
| **Complete, trial expired** | Teaser ranges plus a subscribe CTA                                                              | Subscribing                                 |

The subscribe CTA rides on teaser responses, so an athlete meets it when the trial expires or when they spend the day's calls, not while the trial is answering in full.

## The journey, narrated

**1. You create the athlete and run their first activity calculation.**
You have synced an athlete from your database, maybe just their name and email. You call calculate for tomorrow's 2-hour ride. Saturday answers with a band ("60-80 g carbs/hr"), `profile_complete: false`, a sorted list of missing fields, and an `onboarding.url`. The band is the answer, not a degraded one: Saturday will not compute an exact-looking number out of defaults. The athlete's trial has not started either, so this call costs them nothing.

*Your code:* show the band, and surface the onboarding invite, a button like "Get your exact numbers (2 min)" linking to `onboarding.url`.

**2. The athlete taps the invite.**
They land on a Saturday page co-branded with your platform ("YOURAPP × SATURDAY"), greeted by first name. The page says how many questions are left and offers two paths: answer here, or get the free Saturday app, signing up with the same email they use on your platform so the accounts connect. Either works; the page is the faster first experience.

*Your code:* nothing. The page asks only what is missing, and skips anything you already sent, such as sex or weight.

**3. They answer one question per screen.**
Sweat level, saltiness, carb experience, the same questions Saturday's own app asks, as tap targets. Every answer saves as it is given, so bailing at question 4 still leaves those 4 answers narrowing the bands. The link keeps working and they can come back.

**4. The finish moment.**
On the last answer, the page asks: *"Can we show you fuel for one of your activities?"* If they say yes and you have registered `activity_link_template`, they deep-link straight into your activity screen, where your integration now shows exact Saturday numbers. If not, the page shows their most recent activity's exact targets alongside your `fueling_path_copy` ("In YourApp: open any activity, then the Fuel tab"), and returns them via your `return_url`.

*Your code:* register `activity_link_template` and `fueling_path_copy` on your partner account once. That is what turns Saturday's finish screen into a hand-back into your product at the moment the athlete most wants to be there.

**5. The webhook fires.**
`athlete.profile_completed` arrives once. Their next calculation, and every one after, returns exact numbers, as long as the call also carries the activity's intensity, thermal stress, meal timing, and race flag. The 30-day trial is running; the subscribe CTA handles conversion after that ([Freemium Model](/guides/freemium-model)).

*Your code:* on that webhook, refresh any cached athlete state, and consider marking the moment in your UI: "Your fueling numbers are now exact."

## The app path, narrated

Some athletes already use, or will prefer, the Saturday app. When their app account email matches the email you sent on the athlete record, Saturday links them and their app onboarding feeds your calculations, resolved live rather than synced, with nothing for you to build. Their app answers are never exposed to you through the API. If they turn on "share my fueling profile with \{your platform}" in app settings, the profile values become visible to you as well.

*Tell your athletes:* "use the same email as your \{platform} account". Matching is exact apart from case and whitespace, so a different address never links, and no error surfaces anywhere for you to catch.

## What to build, minimally

1. Show `precision.message` and the invite button whenever `profile_complete` is false.
2. Register `activity_link_template` and `fueling_path_copy` once.
3. Handle `athlete.profile_completed`, if you want to mark the moment in your UI.

Saturday handles the questions, the hosted page, the linking, and the checkout.