Bulk Import Trips via CSV

Bulk trip import allows dispatchers to efficiently create multiple trips in Tobi by uploading a properly formatted CSV file. This article explains how to upload, map, monitor, and understand system rules for trip imports.

Navigate to Trip Import

Go to: Operations → Trip Import Trips

This screen allows you to:

• Upload new trip files
• Track upload history
• Download error logs
• Monitor processing status

Upload History — Field Definitions

• The upload history table displays all files uploaded to the system.
• Unique system identifier for each uploaded file.

Upload Date

Timestamp showing when the file was uploaded.

Uploaded By

Name of the user who uploaded the file.

Total Records / Unprocessed

• Total Records = Total rows present in the CSV file (each row = one record).
• Unprocessed = Number of records that were not processed (trips were not created due to failures).

Success / Failures

• Success = Records for which trips were successfully created.
• Failures = Records for which trips were not created.

Logs

Downloadable error log containing:

• Only failed records
• Failure reason in the last column
• Provided as a CSV file

Status

Indicates the processing state of the file.

Possible values:

• Success — File uploaded successfully
• Draft — File saved in draft mode
• Success (Partially Successful) — File processed but contains failures (error log available)

How to Import Your CSV File

Step 1 — Start a New Upload

Navigate to: Operations → Trip Import Trips → New Upload. You will be taken to the Upload Bookings screen.

Required Field

Fleet: - Select the fleet for which trips should be created

Optional Field

Account: - Use this when uploading trips for a single account.

If uploading for multiple accounts: 

• Do NOT select an account on the upload screen
• Instead, include Account Code in the CSV
• Map it during the mapping step

How to Find Account Code

Go to: Configurations → Accounts → Select Account → 3 dots → Edit

The account code is located under Basic Information if it was entered. If not entered, enter an account code and save it at the account level to be used later.

Example:

In the CSV:

• Add an Account Code column
• Map it during upload
• System will create trips for the corresponding account per record

Step 2 — Upload File and Configure Mapping

• Upload the CSV
• Click Continue
• You will be redirected to the Mapping Screen
• You can:
  • Create a new mapping
  • Use an existing template
  • Clone and modify an existing template once exsiting template is selected

Step 3 — Create a New Mapping Template

Add Mapping Name

• Provide a unique name. This template will be saved for future use.

How to Match Legs

The system requires a unique passenger identifier to correctly group and sequence legs.

You can use any of the following approaches.

Method 1 — Same Invoice Number

Use a column that identifies multiple legs of the same client.

Example:

Leg determination logic:

• Based on pickup time or dropoff time
• The latter time becomes Leg-B

Method 2 — Client Identification

Use a unique identifier per passenger, such as:

• Member ID
• Trip ID
• MRN

Method 3 — Alphabetical Leg Sequence

Example values:

• 4647-A
• 4647-B

The system recognizes these as legs of the same booking.

Client Information Mapping

*Required when Full Name is not mapped

Pickup & Dropoff Information Mapping

Time and Date Fields

Note: At least one valid time configuration is recommended. If none are mapped, trips become Will Call.

Pickup Location Fields

Condition rule: Either full address OR the broken-down components must be mapped.

Dropoff Location Fields

Condition rule: Either full address OR the broken-down components must be mapped.

Trip Information Mapping

Important Notes

• Passenger name and primary phone are mandatory overall.
• Pickup and drop-off addresses are mandatory overall.
• Missing pickup/dropoff times → trips created as Will Call.
• Account Code is required only when uploading for multiple accounts.

Special Requirement Section

This section is optional.

• If your CSV already includes seating needs: Map it directly
• Remove the unused section using the trash icon

Step 4 — Preview and Save

After mapping:

• Click Preview
• Click Save to start import
• Or Save as Draft

Draft Behavior

Draft uploads appear in the upload history, You can later:

• Click the pencil icon
• Submit the draft for processing

System Rules for CSV Trip Import

This section outlines the mandatory requirements, duplicate detection logic, and how the system behaves during trip imports.

Required Fields for CSV Upload

The following fields must be present in every CSV record.

Important:
If any required field is missing, that record will fail and appear in the error log.

System Rules for CSV Trip Import

This section outlines the mandatory requirements, duplicate detection logic, and how the system behaves during trip imports.

Required Fields for CSV Upload

The following fields must be present in every CSV record.

Important:
If any required field is missing, that record will fail and appear in the error log.

Will Call Behavior

Rule

If both pickup time and dropoff time are not mapped, the system automatically creates the trip in Will Call status.

Example — Will Call Creation

Key Point:
Will Call is triggered only when both times are missing.

Passenger Duplicate Detection

The system prevents duplicate passenger profiles using the following hierarchy.

Matching Criteria

• Passenger Name
• Phone Number
• MRN (if present)

Duplicate Logic

Example — Existing Profile Used

Existing in the system

CSV record

Result: Existing profile used (no duplicate created)

Example — Duplicate Profile Created

Existing

CSV

Result: New passenger profile created

Example — MRN Missing

If MRN is not present:

Existing

CSV

Result: Existing profile reused

Trip Duplicate Detection

Currently, trip duplication is evaluated using:

• Passenger Name
• Pickup Address
• Dropoff Address

(Date and time are not part of duplicate logic today.)

Duplicate Behavior

When multiple records (same service date) have identical:

• Passenger
• Pickup address
• Dropoff address

The system behaves as follows.

Example — Duplicate Trip Update

CSV Input

Result

• Only one trip exists
• The second row updates the first with information in second trip
• Error log notes the update

When Trips Are Created Separately

If either pickup or dropoff address differs, the system creates separate trips.

Example — Separate Trips

CSV Input

Result

System creates:

• Leg-A
• Leg-B

Sequential Leg Creation

When multiple distinct records exist for the same passenger, the system automatically sequences legs.

Example — Three Legs

CSV

Result

Interaction with Standing Orders

If a passenger already has a standing order:

• CSV trips get their own leg sequence
• They do not merge with standing order legs

Example

Standing Order (existing)

• Leg-A
• Leg-B

CSV upload adds two new trips

Result

CSV creates:

• Leg-A
• Leg-B

(separate from standing order sequence)

Important Edge Case — Return Trip Uploads

This section explains how the system behaves when outbound and return trips are uploaded separately and how to correctly generate return legs when your source file only contains outbound trips.

Scenario 1 — Single Outbound Trip in CSV

Behavior

When the CSV contains only one outbound trip (Leg-A) for a passenger, the system can correctly attach the return trip (Leg-B) when it is uploaded later.

Example

First Upload (Outbound Only)

System Result

Second Upload (Return)

System Result

Outcome:
The system correctly pairs the return with the outbound trip.

Scenario 2 — Multiple Outbound Records in CSV

Behavior

When the CSV contains multiple records for the same passenger, the system assumes they are sequential legs of one continuous journey.

Because of this, later uploads cannot retroactively pair returns.

Example

First Upload (3 Records)

System Result

Second Upload (Returns)

System Result

Why does this happen?

The system:

• Processes trips in the order received
• Always assigns the next available leg
• Does not retroactively pair earlier legs
• Treats multiple rows as a continuous chain

In Scenario 2, the first upload already consumed:

• Leg-A
• Leg-B
• Leg-C

So the next upload continues with:

• Leg-D
• Leg-E
• Leg-F

Source of Truth — Trip-Level Data from CSV

When importing trips via CSV, the system treats the CSV file as the source of truth for trip-level information.

This ensures that operational trip details always reflect the most recent data provided by the customer’s integration (CIM), even if the passenger profile already exists in Tobi.

Rule

If a passenger profile already exists in the system and the incoming CSV contains different values for trip-level fields, the system will:

• Use the values from the CSV for the trip
• Not override the existing passenger profile
• Apply the CSV values at the trip level

Fields Affected

This applies to trip-level and mapped fields such as:

• Seating Needs
• Primary Phone Number (on trip)
• Secondary Phone Number (on trip)
• Trip Purpose
• Mode
• Tags
• Authorization Number
• Service Type
• Booking Notes

(and any other trip-mapped fields)

How the System Behaves?

Example — Seating Need Override

Existing Passenger Profile

CSV Record

Result

• Passenger profile remains Wheelchair
• Imported trip shows Ambulatory
• CSV is treated as the source of truth for the trip

Example — Phone Number Difference

Existing Profile

CSV Record

Result

• Passenger profile remains 315-555-1111
• Trip uses 315-555-9999

Need Help?

For assistance with CSV imports, contact:

help@tobicloud.com