Athletes
View as MarkdownAthletes are people registered for a sport in the workspace. Use athlete IDs to work with their team assignments, subscriptions, and related records.
On this page
- The athlete object
- List athletesGET
/api/v1/athletes - Retrieve an athleteGET
/api/v1/athletes/{id} - Update an athletePATCH / PUT / POST
/api/v1/athletes/{id} - Delete an athleteDELETE
/api/v1/athletes/{id}POST/api/v1/athletes/{id}/delete - List current athlete subscriptionsGET
/api/v1/athletes/{id}/subscriptions - Preview athlete retirementGET
/api/v1/athletes/{id}/retirement-preview - Retire an athletePOST
/api/v1/athletes/{id}/retirement - Reactivate a retired athleteDELETE
/api/v1/athletes/{id}/retirement - Export athletesGET
/api/v1/athletes/export - Get the season enrollment reportGET
/api/v1/athletes/season-enrollments - Export season enrollmentsGET
/api/v1/athletes/season-enrollments/export
Athletes are people registered for a sport in the workspace. Use athlete IDs to work with their team assignments, subscriptions, and related records.
Attributes
idinteger- Identifier assigned by the API.
sport_idinteger- ID of the sport.
firstnamestring- Given name, up to 60 characters.
surnamestring- Family name, up to 60 characters.
birthdayinteger or null- Date of birth as Unix seconds.
genderstring or null- Use M or F.
phonestring or null- Contact phone.
emailstring or null- Valid contact email.
taxcodestring or null- Tax identification code.
addressstring or null- Street address.
zipstring or null- Postal code.
citystring or null- City of residence.
provincestring or null- Province or region of residence.
countrystring or null- Country of residence.
nationalitystring or null- Nationality.
citizenshipstring or null- Citizenship.
birth_citystring or null- City of birth.
birth_provincestring or null- Province or region of birth.
birth_countrystring or null- Country of birth.
id_numberstring or null- Club registration number. Use a unique value in the sport.
notesstring or null- Athlete notes.
shirt_numberinteger or null- Shirt number.
parent_divorcedboolean- Whether the parents are recorded as separated.
allow_photoboolean- Whether the athlete has given photo permission.
to_notifyboolean or null- Whether the athlete receives notifications.
privacy_consentboolean or null- Recorded privacy consent.
privacy_accepted_atinteger or null- Consent timestamp as Unix seconds.
is_injuredboolean- Set true to record injury status or false to clear it. The API manages injured_at.
metadatamap or null- Custom fields. Supplying the map replaces the existing metadata.
injured_atinteger or null- Time the current injury status began, as Unix seconds.
is_retiredboolean- Whether the athlete is retired.
retired_atinteger or null- Retirement time in Unix seconds.
tscinteger or null- Creation time as Unix seconds.
tsuinteger or null- Last update time as Unix seconds.
/api/v1/athletesLists athlete records in the workspace.
Permissions
Send your API key in X-API-Key. Required permissions are Athletes → Read.
Headers
X-Sport-Idinteger- Use the sport ID to limit the response to one sport.
Query parameters
team_idinteger- Include athletes assigned to this team.
exclude_team_idinteger- Exclude athletes assigned to this team.
plan_idinteger- Filter by a linked subscription plan.
subscription_statusstring- Use active, inactive, pending_activation, or any. The default is any. Use all as an alias for any.
active_onlyinteger- Use 1 to filter to active subscriptions when subscription_status is omitted.
taxcode_exactstring- Exact 16-character alphanumeric tax code.
is_injuredinteger- Use 1 for injured athletes or 0 for other athletes.
qstring- Search name, email, or tax code.
expand_medicalinteger- Use 1 to include medical certificate information.
expand_presubscriptioninteger- Use 1 to include the latest registration request.
view_totalsinteger- Use 1 to include financial totals.
view_membership_totalsinteger- Use 1 to include membership fee totals.
view_membership_statusinteger- Use 1 to include current membership status.
expand_subscription_taxinteger- Use 1 to include the membership fee balance.
expand_monthly_paymentsinteger- Use 1 to include monthly payments. Requires Payments → Read.
payment_month_fromstring- First month, in YYYY-MM format, when expanding monthly payments.
payment_month_tostring- Last month, in YYYY-MM format, when expanding monthly payments.
include_expected_paymentsinteger- Use 1 to include expected payments in the monthly expansion.
lengthinteger- Number of records to return.
startinteger- Zero-based offset.
drawstring- Optional request marker echoed in the response.
sortstring- Sort by id, firstname, surname, email, taxcode, birthday, phone, city, province, country, tsc, tsu, is_injured, is_retired, or supported expansion fields. Prefix the field name with a minus sign for descending order.
orderstring- Direction for unprefixed sort fields. Use asc or desc.
Returns
Returns matching athletes and any requested expansions. Financial totals and their sort fields require Subscriptions → Read and Payments → Read.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- A tax code or monthly payment date range is invalid.
422- One or more fields failed validation.
/api/v1/athletes/{id}Returns one athlete by ID.
Permissions
Send your API key in X-API-Key. Required permissions are Athletes → Read.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the athlete.
Returns
The athlete is returned in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
/api/v1/athletes/{id}Updates an athlete by ID.
Permissions
Send your API key in X-API-Key. Required permissions are Athletes → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the athlete.
Body parameters
firstnamestring- Given name, up to 60 characters.
surnamestring- Family name, up to 60 characters.
birthdayinteger or date string or null- Date of birth in Unix seconds or YYYY-MM-DD format.
genderstring or null- Use M or F.
phonestring or null- Contact phone.
emailstring or null- Valid contact email.
taxcodestring or null- Tax identification code.
addressstring or null- Street address.
zipstring or null- Postal code.
citystring or null- City of residence.
provincestring or null- Province or region of residence.
countrystring or null- Country of residence.
nationalitystring or null- Nationality.
citizenshipstring or null- Citizenship.
birth_citystring or null- City of birth.
birth_provincestring or null- Province or region of birth.
birth_countrystring or null- Country of birth.
id_numberstring or null- Club registration number. Use a unique value in the sport.
notesstring or null- Athlete notes.
shirt_numberinteger or null- Shirt number.
parent_divorcedboolean- Whether the parents are recorded as separated.
allow_photoboolean- Whether the athlete has given photo permission.
to_notifyboolean or null- Whether the athlete receives notifications.
privacy_consentboolean or null- Recorded privacy consent.
privacy_accepted_atinteger or null- Consent timestamp as Unix seconds.
is_injuredboolean- Set true to record injury status or false to clear it. The API manages injured_at.
metadatamap or null- Custom fields. Supplying the map replaces the existing metadata.
Returns
Returns a successful update response.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
422- One or more fields failed validation.
/api/v1/athletes/{id}/api/v1/athletes/{id}/deleteRemoves the athlete record.
Permissions
Send your API key in X-API-Key. Required permissions are Athletes → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the athlete.
Returns
Returns a successful removal response.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
400- The athlete could not be removed.
/api/v1/athletes/{id}/subscriptionsLists current subscriptions for one athlete, ordered by the latest end date first.
Permissions
Send your API key in X-API-Key. Required permissions are Athletes → Read.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the athlete.
Returns
Returns subscriptions that have not expired or been suspended.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
/api/v1/athletes/{id}/retirement-previewEstimates the effect of terminating the athlete’s current or future subscriptions.
Permissions
Send your API key in X-API-Key. Required permissions are Athletes → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the athlete.
Returns
Returns the number of terminable subscriptions and the outstanding amount in minor units.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
/api/v1/athletes/{id}/retirementMarks an athlete as retired and optionally terminates their subscriptions.
Permissions
Send your API key in X-API-Key. Required permissions are Athletes → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the athlete.
Body parameters
subscription_actionstringRequired- Use keep or terminate. Termination also requires Subscriptions → Write.
balance_actionstring- When terminating, use keep_due or waive_remaining. Waiving also requires Payments → Write.
Returns
Returns the updated retirement state, affected subscriptions, amount still due, and number of canceled expected payments.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
422- One or more fields failed validation.
500- The retirement could not be saved.
/api/v1/athletes/{id}/retirementClears the retirement status.
Permissions
Send your API key in X-API-Key. Required permissions are Athletes → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the athlete.
Subscriptions terminated during retirement stay terminated.
Returns
Returns the active status and a null retirement timestamp.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
500- The athlete could not be reactivated.
/api/v1/athletes/exportExports matching athletes to CSV.
Permissions
Send your API key in X-API-Key. Required permissions are Athletes → Read.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Query parameters
team_idinteger- Include athletes assigned to this team.
exclude_team_idinteger- Exclude athletes assigned to this team.
plan_idinteger- Filter by a linked subscription plan.
subscription_statusstring- Use all, active, inactive, pending, or pending_activation. Defaults to all.
subscription_fromdate string- Start of the subscription period in YYYY-MM-DD format. Use with subscription_to.
subscription_todate string- End of the subscription period in YYYY-MM-DD format. Use with subscription_from.
include_groupinteger- Use 1 to include the team.
include_birthinteger- Use 1 to include birth details.
include_contactsinteger- Use 1 to include contact details.
include_residenceinteger- Use 1 to include residence and contact details.
include_consentsinteger- Use 1 to include consent and notification details.
include_parentsinteger- Use 1 to include parent details.
include_parents_extendedinteger- Use 1 to include extended parent details.
include_medicalinteger- Use 1 to include medical certificate dates.
include_identity_docinteger- Use 1 to include identity document validity.
include_paymentsinteger- Use 1 to include balances. Requires Subscriptions → Read and Payments → Read.
include_presubscriptioninteger- Use 1 to include registration request details.
include_membershipsinteger- Use 1 to include membership details.
include_membership_historyinteger- Use 1 to include prior records when including memberships.
include_metadatainteger- Use 1 to include custom fields.
Returns
Returns a CSV attachment containing all matching athletes.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
422- One or more fields failed validation.
/api/v1/athletes/season-enrollmentsLists athlete enrollment progress for one season.
Permissions
Send your API key in X-API-Key. Required permissions are Read on Athletes, Presubscriptions, Subscriptions, and Memberships.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Query parameters
seasonstring- Season label, for example 2026/2027. Defaults to the workspace target season.
cohortstring- Use all, previous, or new.
statusstring- Use all, to_contact, needs_subscription, needs_membership, or complete.
qstring- Search the athlete's name.
athlete_idinteger- Filter by athlete ID.
include_retiredinteger- Use 1 to include retired athletes.
include_contactsinteger- Use 1 to include parent and athlete contacts. Requires Parents → Read.
startinteger- Zero-based result offset.
lengthinteger- Page size from 1 to 100. Defaults to 25.
Returns
Returns enrollment states, counts, season settings and dates, and any warnings. When contacts are requested, the response also includes grouped family contacts.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
422- One or more fields failed validation.
/api/v1/athletes/season-enrollments/exportExports the complete matching enrollment report.
Permissions
Send your API key in X-API-Key. Required permissions are Read on Athletes, Presubscriptions, Subscriptions, and Memberships, and Parents → Read.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
X-Localestring- Use en for English CSV headers and status labels.
Query parameters
seasonstring- Season label, for example 2026/2027. Defaults to the workspace target season.
cohortstring- Use all, previous, or new.
statusstring- Use all, to_contact, needs_subscription, needs_membership, or complete.
qstring- Search the athlete's name.
athlete_idinteger- Filter by athlete ID.
include_retiredinteger- Use 1 to include retired athletes.
group_bystring- Use family to group rows by family contact. The default lists athletes.
Returns
Returns a semicolon-delimited CSV attachment with enrollment and contact details.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
422- One or more fields failed validation.