ASDinCloudDocs

The athlete object

View as Markdown

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.

List athletes

View as Markdown
GET/api/v1/athletes

Lists 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.

Retrieve an athlete

View as Markdown
GET/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.

Update an athlete

View as Markdown
PATCH / PUT / POST/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.

Delete an athlete

View as Markdown
DELETE/api/v1/athletes/{id}
POST/api/v1/athletes/{id}/delete

Removes 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.

List current athlete subscriptions

View as Markdown
GET/api/v1/athletes/{id}/subscriptions

Lists 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.

Preview athlete retirement

View as Markdown
GET/api/v1/athletes/{id}/retirement-preview

Estimates 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.

Retire an athlete

View as Markdown
POST/api/v1/athletes/{id}/retirement

Marks 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.

Reactivate a retired athlete

View as Markdown
DELETE/api/v1/athletes/{id}/retirement

Clears 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.

Export athletes

View as Markdown
GET/api/v1/athletes/export

Exports 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.

Get the season enrollment report

View as Markdown
GET/api/v1/athletes/season-enrollments

Lists 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.

Export season enrollments

View as Markdown
GET/api/v1/athletes/season-enrollments/export

Exports 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.