Teams
View as MarkdownA Team groups athletes and personnel within a sport. Use List teams to find team IDs, then send the team's sport ID in X-Sport-Id for requests that target a specific team.
On this page
- The Team object
- Create a teamPOST
/api/v1/teams - Update a teamPATCH / PUT / POST
/api/v1/teams/{id} - Retrieve a teamGET
/api/v1/teams/{id} - List teamsGET
/api/v1/teams - Delete a teamDELETE
/api/v1/teams/{id}POST/api/v1/teams/{id}/delete - Get team financial totalsGET
/api/v1/teams/summary - Download a team rosterGET
/api/v1/teams/{id}/print - Subscribe team athletesPOST
/api/v1/teams/{id}/subscribe - Send parent portal invitationsPOST
/api/v1/teams/{id}/parent-portal-invites - Assign a team memberPOST
/api/v1/teams_objects - Unassign a team memberPOST
/api/v1/teams_objects
A Team represents a named group within a sport. List and Retrieve return the core fields below. List can also include counts and financial totals.
Attributes
idinteger- The team's identifier within the workspace.
sport_idinteger or null- The sport that owns the team.
namestring- The team name.
archived_atinteger or null- Unix timestamp in seconds when the team was archived. A null value means it is active.
/api/v1/teamsCreates a team in the sport selected by the X-Sport-Id header.
Permissions
Send your API key in X-API-Key. Required permissions are Teams → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the team belongs to.
Body parameters
namestringRequired- The team name, up to 50 characters. Use a unique name within the sport.
archived_atboolean or null- Send
trueto archive using the current time. Sendfalseornullto leave the team unarchived.
The API accepts a key with Teams write access, but the save can fail when the workspace cannot attribute the request to a user. If this happens, create the team in the workspace and use List teams to find its ID.
Returns
Returns a confirmation and the newly created Team object in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks one or more required permissions.
422- Validation failed. This can include a duplicate name in the sport, even if the existing team is archived or deleted.
500- The team could not be saved.
/api/v1/teams/{id}Updates an existing team. PATCH, PUT, and POST accept the same JSON body.
Permissions
Send your API key in X-API-Key. Required permissions are Teams → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the team belongs to.
Path parameters
idintegerRequired- The team ID returned by List teams.
Body parameters
namestring- The team name, up to 50 characters. Use a unique name within the sport.
archived_atboolean or null- Send
trueto archive using the current time. Sendfalseornullto leave the team unarchived.
Omitting archived_at clears it. To keep a team archived, send true. This replaces its archive timestamp with the current time.
Returns
Returns a confirmation. Use Retrieve a team to read the updated fields.
Errors
401- The API key is missing or invalid.
403- The API key lacks one or more required permissions.
404- The team was not found in the selected sport. Requests with missing or unavailable sport context can also return this status.
422- Validation failed. This can include a duplicate name in the sport, even if the existing team is archived or deleted.
500- The team could not be saved.
/api/v1/teams/{id}Retrieves one team by ID in the selected sport.
Permissions
Send your API key in X-API-Key. Required permissions are Teams → Read.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the team belongs to.
Path parameters
idintegerRequired- The team ID returned by List teams.
Returns
Returns the Team object in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks one or more required permissions.
404- The team was not found in the selected sport. Requests with missing or unavailable sport context can also return this status.
/api/v1/teamsLists teams in the workspace. Send X-Sport-Id to list teams for one sport.
Permissions
Send your API key in X-API-Key. Required permissions are Teams → Read.
Headers
X-Sport-Idinteger- Limits the result to one sport. Omit it for the workspace-wide view.
Query parameters
statusstring- Returns active teams by default. Use
archivedfor archived teams orallfor both. qstring- Searches team names. The API also accepts
search[value]. athlete_idinteger- Filters teams by athlete ID. Use only one member filter per request.
coach_idinteger- Filters teams by coach ID.
director_idinteger- Filters teams by director ID.
staff_idinteger- Filters teams by staff ID.
lengthinteger- Positive page size. Omit it to return all matches.
startinteger- Zero-based offset. Defaults to
0. Use it withlength. sortstring- Comma-separated sort fields. Supports
id,name,tsc,tsu, and the three count fields. Prefix a field with-for descending order. orderstring- Defaults to
asc. Usedescfor sort fields without a direction prefix. The list also accepts table-style sorting withorder[0][column],order[0][dir], andcolumns[index][data]. fields[teams]string- Requests derived columns, such as
count_athletes,count_coaches,count_directors. Financial fields require Subscriptions and Payments read access. view_totalsinteger- Send
1to include financial totals and membership counts. Financial totals and sorting bytotal,paid,left, or their aliasestotal_amount,total_paid, andtotal_leftrequire Subscriptions and Payments read access. drawstring- Optional request marker echoed in the response.
Returns
data contains one page of teams. records_total counts teams after the sport, status, and member filters. records_filtered also applies text search. Both counts are before pagination.
Request the count fields explicitly when you need all three membership counts. Without a sport filter, the API can include an embedded sport object.
Errors
401- The API key is missing or invalid.
403- The API key lacks one or more required permissions.
/api/v1/teams/{id}/api/v1/teams/{id}/deleteMarks the team as deleted and removes it from List and Retrieve.
Permissions
Send your API key in X-API-Key. Required permissions are Teams → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the team belongs to.
Path parameters
idintegerRequired- The team ID returned by List teams.
Use Update a team if you want to retain the team in the archived list.
Returns
Returns a confirmation. A repeat request for the same ID returns 404.
Errors
401- The API key is missing or invalid.
403- The API key lacks one or more required permissions.
404- The team was not found in the selected sport. Requests with missing or unavailable sport context can also return this status.
400- The deletion could not be completed.
/api/v1/teams/summaryReturns combined financial totals for teams in the workspace or in a single sport.
Permissions
Send your API key in X-API-Key. Required permissions are Teams → Read, Subscriptions → Read, and Payments → Read.
Headers
X-Sport-Idinteger- Limits the result to one sport. Omit it for the workspace-wide view.
Query parameters
statusstring- Use
archivedfor archived teams. The default covers active teams.
Returns
Returns total, paid, and left as numbers in data. Text search, sorting, and pagination do not affect these totals.
Errors
401- The API key is missing or invalid.
403- The API key lacks one or more required permissions.
/api/v1/teams/{id}/printDownloads the team's roster as a PDF.
Permissions
Send your API key in X-API-Key. Required permissions are Teams → Read.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the team belongs to.
X-Localestring- Use
enfor English. The default is Italian.
Path parameters
idintegerRequired- The team ID returned by List teams.
Returns
The response body contains the PDF file. The example saves it to team-roster.pdf.
Errors
401- The API key is missing or invalid.
403- The API key lacks one or more required permissions.
404- The team was not found in the selected sport. Requests with missing or unavailable sport context can also return this status.
502- The roster PDF could not be generated.
/api/v1/teams/{id}/subscribeCreates a subscription for each athlete currently assigned to the team using an existing plan.
Permissions
Send your API key in X-API-Key. Required permissions are Teams → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the team belongs to.
Path parameters
idintegerRequired- The team ID returned by List teams.
Body parameters
plan_idintegerRequired- The ID of the existing plan to apply.
subscription_startinteger or string- Unix timestamp in seconds or a date such as
2026-12-01. Uses the plan start or current time when omitted. subscription_endinteger or string- Unix timestamp in seconds or a date such as
2027-05-31. Uses the plan end when omitted.
This request can also create expected payments and associated memberships. Check the result before retrying. A retry can create duplicate subscriptions.
The API accepts a key with Teams write access, but subscription saves can fail when the workspace cannot attribute the request to a user. Check which subscriptions already exist before continuing in the workspace.
Returns
created counts successful subscriptions and total counts athletes processed. A 200 OK can also include status: partial and per-athlete errors when some subscriptions could not be saved.
Errors
401- The API key is missing or invalid.
403- The API key lacks one or more required permissions.
400- A plan ID is required or the team has no athletes.
404- The team was not found in the selected sport, or the plan was not found.
500- The request could not finish. Check existing subscriptions before retrying.
/api/v1/teams/{id}/parent-portal-invitesSends or resends parent portal invitations to primary contacts for athletes assigned to the team.
Permissions
Send your API key in X-API-Key. Required permissions are Teams → Write and Parents → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the team belongs to.
Path parameters
idintegerRequired- The team ID returned by List teams.
Returns
Returns counts for contacts considered, invited, skipped, and failed. Check failed even when the request succeeds.
Errors
401- The API key is missing or invalid.
403- The API key lacks one or more required permissions.
404- The team was not found in the selected sport. Requests with missing or unavailable sport context can also return this status.
500- The invitation batch could not be processed.
/api/v1/teams_objectsAdds an athlete, coach, director, or staff member to a team.
Permissions
Send your API key in X-API-Key. Required permissions are Teams → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the team belongs to.
Body parameters
team_idintegerRequired- ID of the team in the selected sport.
object_typestringRequired- One of
athlete,coach,director, orstaff. Athletes and coaches must belong to the selected sport. object_idintegerRequired- ID of the athlete or personnel record.
actionstringRequired- Set to
assign.
Returns
Returns a confirmation. The message key depends on the member type.
Errors
401- The API key is missing or invalid.
403- The API key lacks one or more required permissions.
400- The request was invalid or the member is already assigned.
404- The team or member could not be found for the selected sport and member type.
500- The membership change could not be completed.
/api/v1/teams_objectsRemoves an athlete, coach, director, or staff member from a team.
Permissions
Send your API key in X-API-Key. Required permissions are Teams → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the team belongs to.
Body parameters
team_idintegerRequired- ID of the team in the selected sport.
object_typestringRequired- One of
athlete,coach,director, orstaff. Athletes and coaches must belong to the selected sport. object_idintegerRequired- ID of the athlete or personnel record.
actionstringRequired- Set to
unassign.
Returns
Returns a confirmation even if no association matched. The message key depends on the member type.
Errors
401- The API key is missing or invalid.
403- The API key lacks one or more required permissions.
400- The request was invalid.
404- The team or member could not be found for the selected sport and member type.
500- The membership change could not be completed.