FAQ¶

What variables (metrics) are available via the API?¶

For a complete list with descriptions, see the Variables page.

How can I add a new account to our API consumer ("API client")?¶

Example: I have an existing API connection for our First Team and want to add access to our Academy Team that has a different account.

Adding a new account to your existing API consumer requires two steps:

Firstbeat links the account - Contact sports-cloud-api@firstbeat.com, CSM team or your sales representative. Firstbeat will link your API consumer to that account.
Coach grants access - A Coach on the new account must authorize your API consumer in Sports Cloud:
Go to sports.firstbeat.com
Settings menu → Cloud API section
Select your API consumer and check the account checkbox
Save settings

How can I grant access one of the Firstbeat Sports integration partners access to my account data?¶

The process is similar to adding a new account (see the question above). After you grant access in Sports Cloud, contact your integration partner to complete the setup on their end.

Example: Team is using an AMS system that has integration to Firstbeat Sports Cloud API

Coach contacts Firstbeat to link their Firstbeat account to the AMS System API consumer
Coach grants access for the AMS System API consumer
AMS System completes the connection setup (as needed)

How long does it take for the data to be available via the API?¶

When data is synced to Sports Cloud, it typically takes a few seconds to be available on the Cloud API and elsewhere in the system. If the data is visible on Sports Cloud or in any report, the data is also available via the Cloud API.

Please note that data can arrive on Sports Cloud at different times depending on what kind of data syncing practices the team has. Also, it is common for coaches to create sessions and laps later (evening, next day) as part of the post-analysis process.

Can you deliver the ID of a team or athlete for me?¶

We're happy to help! However, all the IDs you need (athletes, teams, accounts) are included in the API responses themselves, so you can retrieve them directly.

How to find IDs:

Call the relevant endpoint (e.g., /accounts/{accountId}/athletes or /accounts/{accountId}/teams)
The response includes the IDs for all resources
Use these IDs in your integration configuration or system setup

For end-users of partner systems: If you're using a third-party integration (not building your own), please contact your integration provider or internal development team for assistance with configuration.

This self-service approach is often faster than waiting for us to look them up. However, if you're having trouble finding a specific ID or need help navigating the API responses, please contact us at sports-cloud-api@firstbeat.com and we'll guide you through it.

I forgot my consumer ID and/or shared secret¶

As a first step, contact Firstbeat API support at sports-cloud-api@firstbeat.com with the name of your API consumer so it can be disabled.

To restore operations, make a new registration. You can use the same consumer name as with the previous registration. Contact us at sports-cloud-api@firstbeat.com to get the new registration approved and connected to the correct accounts.

How can I rotate the API consumer shared secret?¶

You can rotate your shared secret to a new value if it has been compromised or as part of regular security maintenance.

The rotation process uses a two-step approach to avoid downtime:

Request new secret - Call GET /account/new-secret with a JWT token generated using your current secret. This returns a new secret value that is not yet active.
Confirm new secret - Generate a JWT token using the new secret and call POST /account/new-secret/confirm. This activates the new secret and invalidates the old one.

This two-step process allows you to update your application configuration between steps without service interruption.

Should I use measurement or session data?¶

It depends on your use case:

Measurements - Individual athlete recordings with heart rate data and analysis results
Sessions - Coach-created time ranges grouping multiple athletes for team analysis

Most integrations need both: measurements for individual athlete data and sessions for team-level insights. The best approach is to ask the coaches how they organize their training data, as usage patterns vary between teams.

There are also cases where measurement data is needed although team is mostly using team session data. For example, getting Quick Recovery Test results.

How do I get Quick Recovery Test results?¶

To retrieve Quick Recovery Test results, follow these steps:

Get all athlete IDs for your account:
```
GET /accounts/{accountId}/athletes
```

Filter measurements for Quick Recovery Tests for each athlete:

GET /accounts/{accountId}/athletes/{athleteId}/measurements?measurementType=quickRecoveryTest

Retrieve analysis results using the measurement IDs from step 2:

GET /accounts/{accountId}/athletes/{athleteId}/measurements/{measurementId}/results?var=heartRateLowest,rmssd,quickRecoveryScaledScore,scaledQrtWeeklyMean

The var parameter specifies which variables you want to retrieve. Common Quick Recovery Test variables include: - heartRateLowest - Lowest heart rate during the test - rmssd - Heart rate variability measure - quickRecoveryScaledScore - Recovery score - scaledQrtWeeklyMean - Weekly average recovery score

See Filtering Examples and Variables for more details.

What are manual workouts? Why are some measurements missing variables?¶

Manual workouts don't have any recorded data. They are added by coaches manually.

Consequently, manual workouts don't have all the same analysis results (variables) that regular measurements have. They have only start time, end time, TRIMP, and duration.

How do I know if some data is updated? Are webhooks available?¶

Unfortunately, current version of the API doesn't have webhooks or any API side mechanism to check for new or changed data. To detect changes, you need to implement polling and comparison logic.

Key limitations: - No webhooks for real-time notifications - No lastModified or updatedAt fields - Only startTime-based filtering available for measurements and sessions

Recommended approach:

Incremental sync - Use fromTime parameter to fetch new measurements and sessions since your last sync
Comparison logic - Compare API responses against your local data to detect changes (new IDs, modified properties, added athletes to sessions)
Periodic lookback - Run periodic full syncs (e.g., nightly for last 30 days) to catch edits to historical data

What to check for: * New or deleted athletes, teams, measurements, sessions * Added/removed laps on measurements or sessions * Changed session properties (athletes, start/end times, notes) * Changed measurement properties (start/end times)

For detailed implementation strategies, see our Data Synchronization Guide.

What time format does the API use?¶

All returned time fields follow RFC3339 specification. Data is always returned in UTC time.

Example: Measurement time format.

{
    "athleteId": 416370,
    "endTime": "2023-02-24T08:52:18Z",
    "exerciseType": "Football",
    "measurementId": 10390232,
    "sessionId": 0,
    "startTime": "2023-02-24T08:18:46Z"
}

How do I need to show in my system that data is from Firstbeat Sports?¶

There are millions of ways to mistype Firstbeat

It's not First Beat, FirstBeat or Firstbat

When you're implementing a UI or reporting based on the Firstbeat Sports Cloud API data, we'd like to work with you to ensure Firstbeat and its data are presented accurately. Proper brand attribution and correct representation of our variables and metrics are important to us and help maintain data quality for end users.

We're happy to help you with:

Correct use of Firstbeat branding and trademarks
Accurate presentation of analysis variables and metrics
Terminology and data interpretation guidance
Marketing and user communication support when launching your integration

Please contact us at sports-cloud-api@firstbeat.com to coordinate this review - we look forward to supporting your integration!