Accessing Teams and Rosters
Teams are connected to organizations and contain information such as players, staff, status, program, and all their connected events. Here are a few helpful hints when working with teams:
Creating queries that exceed the complexity score is easy with interconnected data. Refer to the Getting Started article for more information about the complexity score.
A team may have no rostered players or staff. This is common when organizations require several teams before establishing an official roster.
Upload photos for the roster. The most recent profile photo replaces the roster photo if not uploaded.
Parent-affiliated organizations typically see the affiliated team type, the version of the team approved to participate in the affiliation.
Club organizations typically see the primary team type, which is the version they manage on the platform and will appear in mobile applications.
Available Sports for Teams
Each team in SportsEngine can optionally have a sport assigned. Sports assignment happens at a season level; all teams will inherit the sport. While most organizations typically focus on a single sport, knowing the team's sport is essential for organizations that manage multiple sports (e.g., community-based athletics).
Teams will contain the Sport ID, an alphanumeric key identifying the sport.
Sport Name | Sport ID |
Baseball | baseball |
Basketball | basketball |
Canadian Football | canadian_football |
Football | american_football |
Gymnastics | gymnastics |
Ice Hockey | ice_hockey |
Lacrosse | lacrosse |
Other | other |
Rugby | rugby |
Soccer | soccer |
Volleyball | volleyball |
Query by Team ID
If you have the SportsEngine ID for the team, you can quickly access the team and retrieve top-level information. Program is a general term for how this team is participating. It will typically contain the season or tournament name as the primary and the division as the secondary name.
Teams have two status indicators. The top-level status is the overall status and is typically active during and inactive after the season. The second status, rosterStatus, is calculated by Season Management based on meeting the requirements of the season division, including eligibility requirements.
query Team {
team(id: "11eaec3a-9d08-62f8-457g-daf9c14d9c0d") {
created
id
name
gender
type
sport
status
updated
approved
rosterStatus
program {
primaryName
secondaryName
}
players {
firstName
profileId
rosterStatus
jerseyNumber
lastName
}
staff {
firstName
profileId
lastName
rosterStatus
title
}
}
} The most critical attributes to include in a query are players and staff. Players and staff are not paginated, so the lists can be long depending on team use. While those lists contain limited profile data like first and last names, that data is only for the official roster (e.g., legal name). To access complete profile data, use the profileId attribute and profile query.
{
"data": {
"team": {
"created": "2023-09-01T10:05:07.000Z",
"id": "11eaec3a-9d08-62f8-457g-daf9c14d9c0d ",
"name": "Elite 12U National",
"gender": "female",
"type": "affiliate",
"sport": "lacrosse",
"status": "active",
"updated": "2023-09-01T10:05:08.000Z",
"approved": null,
"rosterStatus": "needs_attention",
"program": {
"primaryName": "2023 - 2024 Lacrosse Season",
"secondaryName": "Girls 12's"
},
"players": [
{
"firstName": "Amy",
"profileId": 64578342,
"rosterStatus": "no_approval_required",
"jerseyNumber": "4",
"lastName": "Wong"
},
{
"firstName": "Leela",
"profileId": 4629384,
"rosterStatus": "missing_information",
"jerseyNumber": "1",
"lastName": "Turanga"
}
],
"staff": [
{
"firstName": "Hubert",
"profileId": 3432584,
"lastName": "Farnsworth",
"rosterStatus": "missing_information",
"title": "Head Coach"
}
]
}
}
} Each staff and player has a rosterStatus attribute, which indicates if the specific profile meets the division requirements, including eligibility. While the title attribute typically contains standardized values like Head Coach, there can be affiliation-specific title values by sport and governing body.
Query by Team Codes
Depending on your organization’s configuration, your teams might have autogenerated codes based on affiliation structure. Governing bodies, leagues, or franchises use codes for competitive play. The query supports a search for multiple codes. The results will only contain teams that match precisely (case insensitive). It is important to note that while codes are typically unique, they are not guaranteed to be unique, as they are at the discretion of the affiliation.
query Teams {
teams(organizationId: 12345, codes: [“a-team”], perPage: 100, page: 1) {
pageInformation {
pages
count
page
perPage
}
results {
id
name
gender
type
sport
status
updated
approved
rosterStatus
}
}
}
Query All Teams for an Organization
Sometimes, you will need to go through every team for an organization, so this is where the team's query is helpful. The available filters are status, rosterStatus, and type. Add player and staff attributes if you need player and staff data. For a quick refresher, refer to the Completing First GraphQL Query article when working with pagination.
query Teams {
teams(organizationId: 12345, perPage: 100, page: 1) {
pageInformation {
pages
count
page
perPage
}
results {
id
name
gender
type
sport
status
updated
approved
rosterStatus
}
}
} Connecting Teams and Events
Use the team schema to access an event without additional queries. Users can add this attribute when querying an organization's team or all teams, requiring working with nested pagination. The events can be further filtered by start/end dates if you use this data to populate a time-specific calendar.
query Team {
team(id: "11eaec3a-9d08-62f8-457g-daf9c14d9c0d") {
created
id
name
code
gender
type
sport
status
updated
approved
rosterStatus
events {
pageInformation {
pages
count
page
perPage
}
results {
id
organizationId
name
description
type
status
start
end
created
updated
}
}
}
}