For developers
The Trip Binder file
One ordinary .xlsx that The Trip Binder imports as a whole trip: the trip itself, its cover photo, the roster with contacts and health notes, and the itinerary. If your school website, ticketing system or spreadsheet can write a workbook, it can write one of these.
Where it goes
- New trip → Import a Trip Binder file creates the trip and brings over everything in the workbook in one step.
- Roster → Import roster on an existing trip reads the Roster sheet; the columns arrive pre-mapped and re-imports update travelers in place.
- Schedule → Import Trip Binder file on an existing trip reads the Itinerary sheet and lets you review each stop before it is added.
The workbook
Three sheets, named exactly Roster, Trip and Itinerary. Roster must be the first sheet; the Itinerary sheet is optional. Every cell is plain text — write dates and times as text so a spreadsheet program does not reformat them.
Sheet “Trip”
Key in column A, value in column B, one pair per row, in any order. Keys are matched case-insensitively. Anything else on the sheet is ignored, so it can carry notes for the person opening the file.
| Key | Value |
|---|---|
| Format | Required. Exactly "tripbinder-export/1". Without it the workbook is treated as a plain spreadsheet. |
| Name | The trip name. |
| Destination | Optional. |
| Departure | YYYY-MM-DD or M/D/YYYY. |
| Return | Same. Equal to Departure for a day trip. |
| Cover image | Optional. The path of an image file inside the .xlsx zip, e.g. xl/media/image1.jpeg (JPEG or PNG, under 8 MB). We read the bytes out of the workbook itself — no URL to fetch. |
Sheet “Roster”
A header row, then one row per traveler. Headers are matched by name, case-insensitively, with spaces, underscores and dashes treated alike (“EC1 phone”, “ec_phone_1”). Any column we do not recognize is simply skipped, and the import wizard shows it as “Skip this column”, so extra columns for your own use are fine. Provide at least a name.
| Header | Field | Notes |
|---|---|---|
| First name / Last name | first_name, last_name | Or a single "Name" / "Full name" column, which we split. |
| Middle name | middle_name | Optional. |
| Student ID | student_id | Your own ID for the traveler. Best key for re-imports. |
| Grade | grade | Free text: "10", "Grade 10", "Sophomore". |
| DOB | date_of_birth | YYYY-MM-DD or MM/DD/YYYY. Second key for re-imports (with name). |
| Gender | gender | Optional, free text. |
| Student email | student_email | |
| Parent email | parent_email | The primary guardian; used for guardian invites. |
| Parent name | parent_name | |
| Parent phone | parent_phone | |
| Parent email 2 | parent_email_2 | A second guardian address. |
| Traveler type | traveler_type | Saved as "student" (default), "adult" or "staff". Other words are read: staff / chaperone / teacher / director / coach / nurse → staff; adult / parent / guardian / observer → adult; anything else (and anything mentioning "student") → student. |
| Bus | bus_label | Any label: "Bus 1", "Blue". |
| Allergies | allergies | Free text. |
| Medical notes | medical_conditions | Free text; the catch-all health column. Also matches "Medications", "Medical conditions" and "Health". A cell starting "OTC approved:" is split into over-the-counter medicines and the rest. |
| Dietary restrictions | dietary_restrictions | |
| Over-the-counter medicines allowed | otc_medicines | Free text; also matches "OTC approved" and "Over the counter". |
| Behavioral and other notes | behavioral_notes | Free text; also matches "Behavioral notes". |
| EC1 name / EC1 relationship / EC1 phone / EC1 alt phone / EC1 email | ec_name_1 … | Emergency contact 1. "Emergency contact 1 phone" works too. |
| EC2 …, EC3 … | ec_name_2 …, ec_name_3 … | Up to three contacts. |
The traveler's family can read every one of these columns, and any custom column you add, except custom fields marked Staff only on the Import page.
Re-importing the same file updates existing travelers rather than duplicating them, matched on Student ID first, then name plus date of birth, then name alone.
Sheet “Itinerary”
A header row, then one row per stop. Times are wall-clock in the organizer’s timezone.
| Header | Notes |
|---|---|
| Date | YYYY-MM-DD or M/D/YYYY. Required. |
| Start | 24-hour "HH:MM" or "7:00 AM". Leave empty for an all-day entry. |
| End | Same format. Ignored when Start is empty. |
| Title | Required. Words in it pick the color: depart/bus → travel, lunch/dinner → meal, rehearsal/concert → performance, hotel/check-in → accommodation. |
| Location | Optional. |
| Notes | Optional. Shown under the title. |
A minimal example
Made by hand in Excel or Google Sheets in a couple of minutes: three tabs, these cells.
Sheet "Trip" A B Format tripbinder-export/1 Name 8th Grade DC Trip Destination Washington, DC Departure 2027-04-14 Return 2027-04-16 Sheet "Roster" (first sheet) First name | Last name | Student ID | Grade | DOB | Parent email | Allergies | EC1 name | EC1 phone Ava | Rivera | 100001 | 8 | 2013-04-05 | maria@example.com | Peanuts | Maria Rivera| 610-555-0101 Sheet "Itinerary" Date | Start | End | Title | Location | Notes 2027-04-14 | 07:00 | | Depart school | Bus loop | 2027-04-14 | 12:30 | 13:30 | Lunch | Union Station | Packed lunch 2027-04-14 | | | Free time | Hotel | Until 9 PM
To include a cover photo, add the image file inside the .xlsx (it is a zip) at a path such as xl/media/image1.jpeg and name that path in the Trip sheet’s Cover image row. Libraries that write pictures into worksheets do this for you; a hand-made workbook can simply leave the cover out.
Versioning and privacy
The Format value is tripbinder-export/1. Additions (new optional columns or keys) will not change the number; a breaking change will. A file usually carries health details and family contacts, so treat it like the records it contains: send it over a secure channel and delete it once imported.