Onboarding Guide - TurtleOps

Importing Historical Turtle Data

If your team has been tracking turtles with spreadsheets, paper records, or another system, you can import your existing turtle database into TurtleOps via CSV upload. This lets your team start identifying returning turtles from day one.

Admin-only feature. CSV import is available to organization admins in the Operations tab under Admin Tools.

CSV File Format

Your CSV file should have a header row with the following columns:

Column	Status	Description
`NAME`	Required	Turtle name or identifier. This is the primary label shown in the app - it can be a name, a tag number, or any ID your project uses. Automatically uppercased.
`SPECIES`	Optional	Species name (e.g., Leatherback, Green, Loggerhead). Defaults to your project's primary species if blank.
`LRF`	Optional	Left rear flipper tag number
`RRF`	Optional	Right rear flipper tag number
`RFF`	Optional	Right front flipper tag number
`LFF`	Optional	Left front flipper tag number
`PIT_TAG`	Optional	PIT (microchip) tag number, typically 15 digits
`ADD_TAG_1`	Optional	Additional or historical tag number
`ADD_TAG_2`	Optional	Additional or historical tag number
`ADD_TAG_3`	Optional	Additional or historical tag number

Don't use names? Many projects identify turtles by tag number only. That's fine - just use the primary tag number or any project ID as the NAME value (e.g., WW1234 or STX-0042). The NAME field is simply the label your team will see in the app.

Example CSV

Here's an example using turtle names:

NAME,SPECIES,LRF,RRF,RFF,LFF,PIT_TAG,ADD_TAG_1
GRACIE,Leatherback,WW1234,WW5678,,,982000123456789,
LUNA,Leatherback,WW2345,,WW6789,,982000987654321,OLD567
SHELLY,Green,GR001,GR002,,,,,
CORAL,Hawksbill,,HB100,HB101,,,,HB099

And the same data for a project that uses tag numbers as identifiers:

NAME,SPECIES,LRF,RRF,RFF,LFF,PIT_TAG
WW1234,Leatherback,WW1234,WW5678,,,982000123456789
WW2345,Leatherback,WW2345,,WW6789,,982000987654321
GR001,Green,GR001,GR002,,,
HB100,Hawksbill,,HB100,HB101,,

Empty cells are fine - just leave them blank. The app handles them gracefully.

Excel & PIT Tag Warning

Important: Excel automatically converts 15-digit PIT tag numbers into scientific notation (e.g., 982000123456789 becomes 9.82E+14). This permanently corrupts the data and cannot be reversed. TurtleOps will reject files with corrupted PIT tags to protect your data.

To prevent PIT tag corruption:

Use the template: Download the CSV template from the import screen. The template is pre-formatted to avoid this issue.
Format as Text first: In Excel, select the PIT_TAG column, right-click, choose Format Cells > Text, then enter your data.
Prefix with a quote: Type a single quote before the number ('982000123456789). Excel will treat it as text but won't include the quote in the saved CSV.
Use Google Sheets: Google Sheets does not have this problem - it preserves long numbers as-is.

Already have corrupted data? Go back to your original data source (paper records, database export) and re-enter the PIT tags. There is no reliable way to recover the original number from scientific notation.

How to Import

Navigate to Operations tab
Open the app and go to the Operations tab. Scroll to Admin Tools.
Tap "Import Turtles"
This opens the import screen with instructions and a template download button.
Download the template (optional)
Tap the template button to get a pre-formatted CSV file. Fill it with your data and save as CSV.
Select your CSV file
Tap "Select CSV File" and choose your file. The app will parse it and show a preview of the first 5 rows.
Review the preview
Check that names and tags look correct. Verify PIT tags haven't been corrupted by Excel.
Tap Import
The import runs and shows results when complete - how many turtles were created, skipped, or had errors.

What Happens During Import

The import process handles several things automatically:

Name normalization: All turtle names are uppercased and trimmed for consistency
Duplicate detection: If a turtle with the same name already exists in your organization, the row is skipped (no data is overwritten)
Tag validation: Empty tags, "no tag", and "null" values are treated as blank. If your project has a tag pattern configured, tags are validated against it.
PIT tag check: Scientific notation is detected and the entire import is blocked with a clear error message - no partial imports with bad data
Default species: Rows without a SPECIES value use your project's primary species setting

After the import completes, you'll see a summary:

✅

Created

⏭

Skipped (duplicates)

❌

Errors

Error details are shown per-row so you can fix specific issues and re-import just the failed entries.

Tips for a Smooth Import

Start small: Test with a file of 5-10 turtles first to verify formatting before importing your full dataset
One import at a time: Import handles duplicates by name, so you can safely run multiple imports without creating duplicate records
Historical tags: Use ADD_TAG_1, ADD_TAG_2, and ADD_TAG_3 for old flipper tags that were replaced. These are stored as additional tags and searchable in the app.
No observations: CSV import creates turtle profiles only. Observation history (encounters, nesting records) should be entered through the app or the web dashboard.
Re-import safe: If you make a mistake, you can delete turtles individually and re-import. Duplicates are skipped automatically.

After Importing

Once your turtles are imported:

Verify in the Turtles tab: Browse your turtle list to confirm names and tags imported correctly
Invite your team: Generate invite codes from the Operations tab and share them with your volunteers and coordinators
Configure your project: Set your beach location, nesting season dates, required photos, and measurement preferences in Project Setup
Set up turtle alerts: Create alerts for turtles of special interest - injured turtles, research subjects, or turtles that shouldn't be disturbed

See the Quick Start Guide for a full walkthrough of setting up your team.

Need Help?

Contact us at hello@turtleops.org and we'll help you get your data imported.