Getting Started

Introduction

The Teams API allows developers to interact with team-based fitness tracking data used in sports training and monitoring. You can manage user accounts, retrieve performance metrics, and integrate with various fitness tracking providers.

User Management

Coaches

Coaches are central to the Teams API, as they manage athletes and their associated data.

Creating a Coach

To begin using, you'll need to register a coach account.

This involves providing necessary credentials and integration specifics related to the provider you're integrating with (e.g., VALD, Catapult).

Endpoint: POST /coaches

Description: Registers a new coach with the specified provider.

Required Fields:

• reference_id: Your internal identifier for the coach.

• provider: The integration provider (e.g., VALD, CATAPULT).

• Provider-specific authentication fields (e.g., client_id, client_secret, token).

Note: After creating a coach, you'll receive a coach_id generated by the server, which you'll use for subsequent operations.

Deleting a Coach

If you need to remove a coach and all associated data, you can delete the coach account.

Endpoint: DELETE /coaches/{coachId}

Description: Deletes a coach and all associated athletes, activities, and tests.

Required Parameter:

• coachId: The unique identifier of the coach to be deleted.

Warning: This action is irreversible and will remove all data related to the coach.

Athletes

Athletes are managed under coaches and represent the individuals whose performance data you're tracking.

Managing Athletes

While athletes are typically synced from the provider's system, you can retrieve and update athlete information as needed.

Endpoint to List Athletes: GET /coaches/{coachId}/athletes

Description: Retrieves all athletes under a specific coach.

Required Parameter:

• coachId: The unique identifier of the coach whose athletes you want to list.

Getting Data

Activities

Activities represent performance sessions or events recorded by athletes.

Fetching Activities

You can retrieve all activities recorded by athletes under a specific coach.

Endpoint: GET /coaches/{coachId}/activities

Description: Retrieves activities within a specified time range for all athletes under the coach.

Required Parameter:

• coachId: The unique identifier of the coach.

Optional Query Parameters:

• start_time: Start of the time range (ISO 8601 format).

• end_time: End of the time range (ISO 8601 format).

Fetching Activity Schemas

To understand the structure of activity metrics available, you can fetch the activity metrics schema.

Endpoint: GET /coaches/{coachId}/activities/metrics/schema

Description: Returns the schema of activity metrics for the specified coach.

Required Parameter:

• coachId: The unique identifier of the coach.

Tests

Tests are specific assessments or measurements conducted with athletes.

Fetching Tests

You can retrieve all tests conducted by athletes under a specific coach.

Endpoint: GET /coaches/{coachId}/tests

Description: Retrieves tests within a specified time range for all athletes under the coach.

Required Parameter:

• coachId: The unique identifier of the coach.

Optional Query Parameters:

• start_time: Start of the time range (ISO 8601 format).

• end_time: End of the time range (ISO 8601 format).

Additional Features

Webhooks

Webhooks allow your application to receive real-time notifications when certain events occur, such as coach registration or athlete data updates.

Available Webhooks:

• coach.registered: Triggered when a new coach is registered.

• athlete.registered: Triggered when one or more athletes are registered.

Setting Up Webhooks:

You'll need to configure your endpoint to receive webhook events and handle them appropriately. Ensure your endpoint is secure and can process the data received.

Handling Enums

The API uses various enumerations (enums) to represent specific sets of values for certain fields, such as Sport, Position, Movement, etc.

Examples of Enums:

• Sport: Indicates the type of sport (e.g., FOOTBALL, BASKETBALL).

• Side: Indicates the side of the body (LEFT, RIGHT, BOTH).

• MetricType: Indicates the type of metric (FORCE, VELOCITY, POWER).

Usage:

When processing data from the API, you'll encounter integer values representing these enums. Refer to the enum definitions provided in the API documentation to interpret these values correctly.

Integrating with Providers

The Teams API supports integration with various fitness tracking providers. Each provider may have specific requirements for authentication and data retrieval.

Fetching Provider Details:

Endpoint: GET /integrations/detailed

Description: Returns detailed information about available providers, including required login fields and logos.

Provider-Specific Fields:

When creating a coach or integrating with a provider, you'll need to supply provider-specific authentication fields such as client_id, client_secret, or token.

Example Providers:

• VALD: May require client_id and client_secret.

• Catapult: May require an API token.

Note: Always refer to the provider's documentation for the most accurate and up-to-date integration requirements.

Conclusion

This guide provides an overview of how to get started with the Teams API for managing coaches, athletes, and retrieving performance data. By following the endpoints and guidelines outlined above, you can effectively integrate the Teams API into your application.

For detailed information on each endpoint, including request and response formats, please refer to the API reference documentation.

If you have any questions or need further assistance, feel free to reach out to our support team.