Migration & Import

NextRoute's migration tool lets you import your existing customer base from CSV files or migrate directly from other route management platforms. The tool handles address geocoding, service zone matching, and route template syncing automatically.

Who Can Use This

Migration endpoints require the owner role. Only account owners can run imports to prevent accidental data changes.

Supported Import Sources

CSV Files

Upload a standard CSV file with your customer data. The migration tool auto-detects columns and maps them to NextRoute fields.

Required columns (at minimum):

• Name (or First Name + Last Name)
• Address (service address)

Optional columns:

• Email, Phone
• Service plan name
• Service zone name
• Bin count, bin size, bin location
• Trash day, notes
• Custom fields

Platform-Specific Imports

NextRoute auto-detects CSV exports from popular platforms and maps columns automatically:

• MyRoutePro (jobs.csv) — detects PackageName and ServiceZone columns
• MyRoutePro (customers.csv) — detects StreetAddress and StatusName columns
• Generic CSV — auto-maps common column names

Import Workflow

Step 1: Analyze Your File

Before importing, upload your CSV for analysis. The system will:

• Parse the CSV and detect the column layout
• Identify the source platform (if applicable)
• Map columns to NextRoute fields
• Return a preview of matched columns and sample data

curl -X POST https://api.nextroute.app/api/migration/analyze \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"csv_content": "Name,Address,Email,Phone\nJohn Doe,123 Main St,john@example.com,555-0100"}'

Step 2: Review Mappings

Review the detected column mappings and adjust if needed. The analysis response includes:

• platform — detected source platform
• mapping — column name to NextRoute field mapping
• preview — first few rows of parsed data
• total_rows — number of records to import

Step 3: Run the Import

Execute the import with your confirmed mappings:

curl -X POST https://api.nextroute.app/api/migration/import \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "csv_content": "...",
    "mapping": {
      "name": "Name",
      "address": "Address",
      "email": "Email",
      "phone": "Phone"
    },
    "options": {
      "geocode": true,
      "match_zones": true,
      "match_plans": true,
      "send_welcome_emails": false
    }
  }'

Step 4: Monitor Progress

For large imports, the tool creates a background job. Monitor progress with:

curl https://api.nextroute.app/api/migration/job/JOB_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

What Happens During Import

For each row in your CSV, the migration tool:

1. Parses the row using the column mapping
2. Geocodes the address using Mapbox to get lat/lng coordinates
3. Matches service zones — finds the zone that contains the address
4. Matches service plans — matches plan names (case-insensitive, supports partial matching)
5. Creates the customer record with all mapped fields
6. Creates a property with the service address, zone, and plan
7. Syncs to route templates — adds the customer to the appropriate route template based on their zone

Post-Import Tools

Geocode Addresses

If you imported without geocoding, you can batch-geocode later:

curl -X POST https://api.nextroute.app/api/migration/geocode \
  -H "Authorization: Bearer YOUR_TOKEN"

Backfill Zone Boundaries

Recalculate zone boundaries based on the addresses of customers in each zone:

curl -X POST https://api.nextroute.app/api/migration/backfill-zone-boundaries \
  -H "Authorization: Bearer YOUR_TOKEN"

Send Welcome Emails

Send welcome emails to all imported customers who have not yet received one:

curl -X POST https://api.nextroute.app/api/migration/send-welcome \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "welcome"}'

Handling Errors

The import returns a detailed report:

{
  "imported": 142,
  "skipped": 3,
  "errors": [
    { "row": 15, "error": "Missing required field: name" },
    { "row": 89, "error": "Duplicate email: john@example.com" },
    { "row": 102, "error": "Geocoding failed for address" }
  ]
}

Rows with errors are skipped — they do not block the rest of the import. Review the error report and fix any issues manually in the dashboard.

Best Practices

• Run the analyzer first to verify column mappings before importing
• Start with a small test — import 5-10 rows to verify everything looks right
• Back up your data before running a large import
• Disable welcome emails during initial import to avoid flooding new customers
• Enable geocoding to ensure accurate zone matching and map display
• Review duplicate detection — the import skips rows where email or address already exists

Related

• Customers & Properties — how imported data is structured
• Service Zones — zone matching during import
• Service Plans — plan matching during import