Organizations & Teams

Import rosters and claim players

Add organization players by hand or from a CSV file, review possible matches, send claim invitations, and connect each roster record to the athlete's own HustlX account.

Use this guide when your player list is in a spreadsheet, or when your athletes do not have HustlX accounts yet. You end up with organization player records, organization-owned teams, filled rosters, and a safe way for each athlete to take over their record.

Only an Organization Administrator can import a CSV or send an organization-player claim link. Anyone with league or training management can add and edit players by hand.

An imported or hand-added player is a not-claimed player: a roster record, not a login account. It has no password and cannot sign in, but it can sit on a team, play, and collect statistics. For guest players on a personal team, community players, and paying for a training participant, see Anonymous Players & Walk-ins.

Add one player by hand

Open Players

Open your organization, select Manage, then Roster > Players. From here you can add, import, search, edit, and claim players.

Fill in the player

Select Add Player. Player Name and Sport are required. Contact Email, Status, Tags, Player photo, and Cover image are optional.

Save

Select Save Player. Save creates a not-claimed roster record, not a login account.

Leave Contact Email blank when you do not have it yet, then edit the player and add it later. The address stays private to authorized organization staff, and nothing is sent to it until you start a claim. Set the jersey number and position later on the team roster, because they can differ between teams.

Import players from a CSV file

Download the template

Select Import CSV, then Download example CSV to start from the accepted column layout.

Fill in the columns

Only name and sport are required. See CSV columns below for the optional team, key, email, and staff columns.

Choose whether to send invitations

Send invitations to emails in this file is on by default. After the import completes, each player whose row has an email receives a link to claim their record with their own account. Turn the checkbox off to import without sending anything.

Upload

Choose one or more files and select Upload CSV. Each file can be up to 5 MB and 1,000 rows; you can upload up to 10 files at once, 25 MB in total. You can keep working while HustlX checks each file.

CSV columns

ColumnWhat to enter
name (required)The player's full name
sport (required)A lowercase sport code, such as basketball or volleyball
teamThe organization-owned Team for the player
tagsTeam tags separated by a pipe, such as 18U|Blue
team_key, player_keyStable keys from an earlier roster file, when you have them
emailSaved as the contact email and used for claim invitations
team_roleplayer, admin, coach, or manager. Blank means player
captainyes or no (y, true, 1 and n, false, 0 also work)
jersey_number, positionThe player's number and position on that Team
coach_name, assistant_coach_name, assistant_coach_name_2Staff names, used only when HustlX creates a new Team

Rows with the same team, tags, and sport go to one Team, and HustlX creates a missing organization-owned Team. A row that sets team_key, jersey_number, position, tags, team_role, or captain also needs a team value. Stable team_key and player_key values identify the intended record even when names repeat; keep them in later versions of the file to reduce repeated review. The example CSV does not include the tags or assistant_coach_name_2 column, so add those headers yourself when needed. The import never creates login accounts, and it ignores password and unknown columns.

Review matches and finish the import

An import moves through these statuses: Queued, Checking roster, Review required (only when a name may match an existing record), Approved, queued, Processing, then Completed or Failed. At Review required, no roster changes from that file have been made yet. Imports are all-or-nothing: if any row is invalid, the whole file fails and nothing is written.

Open the review

On the status banner, select Review matches for the waiting file. Each item shows the imported value, its CSV row numbers, and the current roster details.

Decide each Team

Choose Use existing, Create new Team, or Skip team. Create new Team keeps the same imported name and needs at least one manually chosen tag, such as 18U. Skip team also skips the players listed under it.

Decide each player

Choose Use existing, Create separate player, or Skip player. Use Create separate player when two different people share the same name.

Continue

Select Continue import once every item has a choice. Use existing does not overwrite the current name, coaches, claim status, jersey number, position, or Team assignment. If the roster changes while you review, HustlX refreshes the matches and asks again.

Among organization-owned Teams in one organization and sport, each normalized exact Team name must use a unique tag combination. Tag comparison is case-insensitive and order-insensitive, so 18U, Blue conflicts with blue, 18u. User-owned and claimed Teams are never import candidates.

When the import completes, check the totals for created players, created teams, and team attachments. If invitations were on, the banner also shows a line such as "12 invitations sent · 2 skipped (1 already claimed, 1 without an email)". Invited players show Invited until they accept; import invitations expire after 7 days. A row is skipped when it is already claimed, already invited, has an account linked to a different player in this organization, is without an email, or is over the daily invitation limit of 1,000 per organization.

Check team rosters

Open Manage > Roster > Teams and select Manage roster on the team card. Confirm each player's jersey number and position, and add anyone missing. Rows with a consistent team and sport are already attached. If you created a same-name Team, both cards appear with their own tags and key suffixes.

Connect a player to their HustlX account

Claiming creates a one-way link between the roster record and one HustlX account. The roster, match, and statistic history stays attached. It is not a merge and must never combine records that belong to different people. Claim status never blocks game day.

Start the claim

In Manage > Roster > Players, open the player's actions menu and select Claim. The Send roster claim link window opens.

Pick and confirm the account

Select the correct HustlX account, then confirm the athlete's name and email address with them.

Select Send claim link. The athlete opens the email and accepts the roster profile from their own verified HustlX account. You cannot accept for them.

Confirm the result

After the athlete accepts, confirm that the linked username belongs to them.

A claim link lasts 24 hours, and a record can have one pending claim link at a time. One HustlX account can own one organization-player record per organization. Claimed players are managed by the athlete and can no longer be edited or deleted from the roster tools. See Invitations and Notifications for the athlete's steps.

Troubleshooting

A failed file lists each problem as "Row N (field): message". Nothing from that file was created.

What you seeWhat to do
A file count, 5 MB, or 25 MB limit messageRemove files, or split a large roster.
"Too many roster imports are already queued for this organization..."Finish Review required files and wait for queued ones (25 unfinished at most).
The file must be a csv or txt fileSave as CSV UTF-8 with a .csv extension.
"Too many rows (1250). Maximum is 1000."Split the roster into files of 1,000 rows or fewer.
"Unknown sport: Basketball."Use the lowercase code, such as basketball.
"Team is required when ..."Add the team value, or clear the team-only cells.
"This email is already on another roster record in this file. ..."Keep the email on one row, or use the same player_key for one player.
"Replay of import #12. No changes applied."Nothing to fix. The same file was already imported.

The wrong account was selected

Close the window before sending and start again. If the wrong person already accepted, do not delete either record; contact HustlX Support with the organization, player, and account details.

Check the selected account's email, then send a new link once the current one expires. For CSV invitations, read the banner's skip reasons first.

The account is already linked

Use the existing linked record. Never delete a roster record as a workaround, because it may hold match and statistic history.

  1. Manage teams and rosters
  2. Create a league
  3. Match readiness
  4. Game day overview