Pocket8 Player Import CSV Specification
The Player CSV import allows league organizers and club admins to bulk-upload their player rosters into Pocket8. With built-in intelligent column mapping, PapaParse streaming, and automatic entity provisioning, Pocket8 automatically creates missing teams and divisions on the fly and generates player claim invite codes instantly.
How the Pocket8 CSV Uploader Works
From spreadsheet export to claimed digital player cards in three automated steps.
PapaParse Upload & Detection
Upload your UTF-8 comma-separated CSV. Pocket8 uses high-speed PapaParse to parse rows client-side and automatically inspects your column headers using case-insensitive alias matching.
Interactive Column Mapping
If your spreadsheet uses customized header labels, the 2-step mapping modal lets you visually pair your columns to Pocket8 fields or switch between Split Name and Single Full Name mode.
Auto-Provisioning & Invite Codes
When confirmed, Pocket8 creates any missing divisions and teams automatically, links player profiles via teamId, and mints unique invite codes for login access.
Recommended Standard CSV Formats
Using standard header names allows Pocket8 to auto-detect all columns instantly without requiring manual mapping.
Option A: Split Names (Separate First & Last Names)
Best when your spreadsheet already separates given names and surnames. This format ensures 100% precision with hyphenated or multi-word family names.
Sample Data Preview
5 sample player rows| first_name | last_name | team | division | external_id |
|---|---|---|---|---|
| Marcus | Sterling | Rack & Rollers | Premier Division | PL-101 |
| Oliver | Hayes | Rack & Rollers | Premier Division | PL-102 |
| Liam | Gallagher | The Break & Dish Club | Premier Division | PL-201 |
| Sarah | Jenkins | Corner Pocket Aces | Division 1 | PL-301 |
| David | O'Connor | Corner Pocket Aces | Division 1 | PL-302 |
Raw CSV Format
first_name,last_name,team,division,external_id Marcus,Sterling,Rack & Rollers,Premier Division,PL-101 Oliver,Hayes,Rack & Rollers,Premier Division,PL-102 Liam,Gallagher,The Break & Dish Club,Premier Division,PL-201 Sarah,Jenkins,Corner Pocket Aces,Division 1,PL-301 David,O'Connor,Corner Pocket Aces,Division 1,PL-302
Supported Fields & Accepted Header Aliases
Pocket8 inspects column headers (case-insensitive, trimming spaces) to auto-map fields. If your spreadsheet headers match any recognized alias below, they map automatically.
| Field | Required? | Accepted Header Aliases (Auto-Detected) | Description & Processing Behavior |
|---|---|---|---|
First Name* | Yes (unless Full Name is used) | first namefirstnamefirst_name | Player's given name. If blank but Last Name exists, defaults to "Unknown". |
Last Name* | Yes (unless Full Name is used) | last namelastnamelast_namesurname | Player's surname / family name. If blank but First Name exists, defaults to "Unknown". |
Full Name* | Yes (only in single-column mode) | full namefullnamefull_namename | When selected, Pocket8 splits on spaces: the last token becomes lastName, and the preceding tokens become firstName. |
Team | Optional | teamteam_nameteamnameteam namesquadgroup | The team this player belongs to. Auto-creates the team if it does not yet exist. Case-insensitive matching. |
Division | Optional | divisiondivision_namedivisionnamedivision name | The division / bracket the player participates in. Auto-creates the division if it does not yet exist. Case-insensitive matching. |
External ID | Optional | idplayeridplayer_idexternalidexternal_id | Member number, league license ID, or external system ID (e.g. EPA / APA / BAPTO ID). Saved on the player profile and searchable. |
Automatic System Actions on Import
Pocket8 performs five automated tasks in real-time when an organizer confirms the roster upload:
1. Division Auto-Creation
Pocket8 checks existing divisions in your organization. Any division names in the CSV not already in the database are created automatically with zero pre-configuration.
2. Team Auto-Creation
Pocket8 checks existing teams in the organization. Any team names in the CSV not already in the database are created automatically and assigned to their division.
3. Player Roster Linking
The player profile is created and linked directly to their assigned team via teamId, placing them immediately on the active matchday sheet.
4. Invite Code Generation
Pocket8 generates a unique, random alphanumeric invite code for every imported player (e.g. ABC-123). Players use this code to claim their player passport and sign in.
5. De-duplication & Whitespace Sanitization
Leading and trailing whitespaces are automatically trimmed from names, IDs, teams, and divisions. Team and division lookups use normalized, case-insensitive comparison to avoid accidental duplicate clubs or divisions.
File Formatting Rules & Requirements
Standard comma-separated format from Excel, Sheets, or Numbers.
Supports international player accents, apostrophes, and symbols.
Semicolons or tab separators must be converted to standard commas.
Values with commas (e.g. "Smith & Sons, Pool") must be double-quoted.
At least 1 header line and 1 data row with a valid player name.
Live Player CSV Validator Sandbox
Paste your spreadsheet CSV to test column auto-detection, auto-provisioning preview, and syntax validity before uploading to Pocket8.
Player Import Frequently Asked Questions
Everything you need to know about bulk roster onboarding, name splitting, and invite codes.
Ready to configure your full league season?
Head over to our step-by-step League Setup Guide to configure match rules, tables, and fixtures.