PragmaticTours User Manual

Welcome to PragmaticTours! This guide explains how to use the platform in your daily work. It is written for tour agency staff — dispatchers, coordinators, guides, and administrators.

Table of Contents

  1. Getting Started
  2. Your Dashboard
  3. Calendar View
  4. Managing Tours
  5. Product Catalog
  6. Fleet Management
  7. Team Management
  8. Dispatch & Assignments
  9. Auto-Assignment & Optimization
  10. Passenger Manifests
  11. Equipment & Inventory
  12. Financial Reports
  13. Payable Report
  14. User Settings
  15. Account Settings
  16. API Reference (v1)

1. Getting Started

Logging In

Open your browser and go to your agency's address (e.g., https://youragency.pragmatictours.com). You can log in with:

  • Email and password — the account your admin created for you.
  • Google or Microsoft account — if your agency has turned on this option.

First Time

If you received an invitation by email, click the link in the email. It will take you to a page where you can set up your password. After that, you will be taken to your agency's workspace.

The Main Navigation

Once logged in, you will see a sidebar on the left with these sections:

Menu Who Can See It What You Can Do
Dispatch Everyone See today's tours and assign staff/vehicles
Calendar Everyone View the monthly schedule
Manifests Admins, Dispatchers Upload and process passenger lists
Inventory Admins, Dispatchers Manage equipment
Catalog Admins only Create tour templates
Fleet Admins only Add and manage vehicles
Team & Invites Admins only Invite and manage staff
Reports Admins only View daily revenue, costs, and profit
Payable Report Admins only View freelance and vehicle costs
API Keys Admins only Generate and revoke API keys
Settings Everyone Access account and profile settings

Top Bar

At the top of the page you will find:

  • Current date — displayed on the left.
  • Notification bell — (admins and dispatchers only) shows a red badge with your unread count. Click to open a dropdown with recent notifications (new assignments, acceptances, cancellations, reschedules). Click "View all notifications" to see the full list. Notifications arrive in real time — no page refresh needed.
  • User dropdown — your initials, name, and role on the right. Click to quickly access Profile, Communication Preferences (only when Telegram or WhatsApp channels are enabled), Change Password, Availability Settings, or Sign Out. If you belong to multiple agencies, you can switch accounts or create a new agency here.

2. Your Dashboard

The Dispatch page is your main workspace. It shows you everything happening on a selected day.

Choose a Date

At the top of the page you will see: - A date picker — click to select any date. - Previous / Next day arrows — move one day at a time. - Today button — jumps back to the current date.

What You See

Each tour on that day appears as a card. Every card shows:

  • Tour name — e.g., "Snorkeling Adventure".
  • Status — Scheduled, In Progress, Completed, or Cancelled.
  • Passenger count — how many people are on this tour.
  • Capacity — seats filled vs total assigned.
  • Assigned staff — guides, drivers, and captains already assigned.
  • Assigned vehicles — buses, vans, or boats already assigned.
  • Missing resources — roles or vehicles that still need to be filled.
  • Cancel reason dialog — clicking Cancel opens a modal where you enter a reason for the cancellation.

Multi-Day Tours

When a tour was created from a multi-day template, it appears as a single card with a Multi-Day (N days) badge. The card shows:

  • Parent tour header — the package name and date range (e.g., "Jun 10 – Jun 13").
  • Day N badge — indicates which day of the multi-day tour is currently displayed.
  • Child tour name — the specific day plan name, shown below the pickup time.
  • Child tour data — pickup time, address, assignments, and manifest for that specific day, not the whole package.
  • Cancel — cancels the entire multi-day tour and all its child tours.
  • Cancel Day — cancels only the individual day (child tour) shown on the card, without affecting the rest of the package.
  • Reschedule (all days) — shifts all child tour dates by the same offset.

Fleet Status

On the right side of the dashboard you will see the Fleet Status panel. It shows every active vehicle in your fleet (excluding disabled vehicles) and its status for the selected day:

Status Meaning
Available (green) Vehicle is free and ready for assignment.
In Maintenance (red) Vehicle has a scheduled maintenance block. It will not be suggested by the optimizer.
Unavailable (red) Vehicle is already assigned to another tour on this day (overlapping time).

3. Calendar View

Click Calendar in the sidebar to see a monthly view.

  • Each day shows a count of how many tours are scheduled.
  • Multi-day tours appear on every day they span, not just their start date.
  • Click any day to see a detailed list of all tours on that date. For multi-day tours, the day detail shows the specific child tour data for that day, including the child tour name below the pickup time.
  • Use the arrows or the "Today" button to navigate.
  • The calendar respects your role: guides only see the tours they are assigned to.

4. Managing Tours

Creating a New Tour

The tour creation form adapts based on the template you select. Templates can be single-day or multi-day (see the Product Catalog section).

Single-Day Tour

  1. Go to the Dispatch page for the desired date.
  2. Click "New Tour".
  3. Select a single-day template from the catalog.
  4. Fill in:
  5. Date — defaults to the current day.
  6. Passenger Count — how many people will join.
  7. Pickup Time — required. End Time is auto-calculated from the template duration; you can adjust it later when editing.
  8. Pickup Address — required.
  9. Drop-off Address — optional.
  10. Transit Duration — how long it takes to get there.
  11. Status — default is Scheduled; you can also start the tour immediately.
  12. Staff Compensation — choose between Gig Rate (flat fee per tour) or Hourly Rate. Can be overridden per assignment.
  13. Price per Pax — auto-filled from the template, can be overridden.
  14. Click Save.

Multi-Day Tour

  1. Go to the Dispatch page for the desired start date.
  2. Click "New Tour".
  3. Select a multi-day template (identified with a "Multi-Day" badge in the dropdown).
  4. The form automatically switches to multi-day mode:
  5. Start Date — the first day of the tour (defaults to the selected date).
  6. End Date — auto-calculated from the start date + number of day plans; you can still override it.
  7. Single-day fields (pickup time, pickup address, etc.) are hidden — each day plan on the template provides its own values.
  8. A banner shows how many day plans the template includes.
  9. Fill in Passenger Count, Status, and Staff Compensation — these are shared across all days. The price is auto-calculated from the sum of each day plan's price.
  10. Click Save.

Behind the scenes, the system creates: - A parent tour (multi-day category) with the date range. - One child tour per day plan, each with its own date, pickup time, pickup address, and price per passenger — taken from the single-day template assigned to each plan.

Child tours inherit the passenger count from the parent. Each child can be managed individually from the dashboard or calendar — assign staff, upload manifests, or cancel a single day without affecting the rest of the package.

Form Validation

Before the form is submitted, the system checks that all required fields are filled in. If any required field is empty, the form will show an alert listing the missing fields and highlight them in red. The form will not submit until all required fields are filled.

Required fields include: - Template — must be selected. - Date (single-day) or Start/End Date (multi-day) — must be set. - Passenger Count — must be greater than zero. - Pickup Time and Pickup Address (single-day) — required. - Transit Duration (single-day) — required.

Tour Statuses

  • Scheduled — the tour is planned and ready for assignments.
  • In Progress — the tour has started.
  • Completed — the tour is finished.
  • Cancelled — the tour will not run. When a tour is cancelled, the card only shows the tour name, status, and cancellation reason (if one was entered) or a "Rescheduled" note. The Required Resources, Equipment Checklist, and Manifest & Assignments sections are hidden.

Editing a Tour

Click on a tour card, then select Edit. You can change any of the details. Once a tour has started, you cannot edit or remove assignments anymore.

Uploading a Manifest to a Tour

From the tour page, you can upload a CSV passenger manifest directly. See the Passenger Manifests section for details.

Cancelling a Tour

Only admins and dispatchers can cancel a tour. A tour must be in Scheduled status to be cancelled.

  1. Open the tour card on the dashboard.
  2. Click Cancel next to the Edit button.
  3. A dialog appears asking for a reason for cancellation. Enter the reason and click Confirm Cancel.

For multi-day tours: - Cancel (parent) — cancels the entire multi-day tour and all its child tours. - Cancel Day — cancels only the individual day (child tour) shown on the card, leaving the rest of the package intact.

When a tour is cancelled: - All pending and confirmed assignments are set to Cancelled. - All equipment check-outs are released. - A cancellation notification email is sent to every confirmed guide and driver. - The tour's status changes to Cancelled and it is moved to the past.

The cancellation reason, who cancelled it, and when are recorded for audit purposes. Once cancelled, the tour card collapses to show only the name, status, and reason — all operational sections (resources, assignments, manifest) are hidden.

Rescheduling a Tour

Rescheduling moves a tour to a new date while preserving its passenger manifest and trying to keep the same staff and vehicles.

Only admins and dispatchers can reschedule. A tour must be in Scheduled status to be rescheduled.

  1. Open the tour card on the dashboard.
  2. Pick the new date using the date picker next to Reschedule.
  3. Click Reschedule.

For multi-day tours: - The button reads "Reschedule (all days)". - All child tour dates are shifted by the same number of days as the parent's start date. - Individual child tours cannot be rescheduled separately.

Behind the scenes: - A new tour is created on the new date with the same settings (pax count, pickup times, addresses). - The passenger manifest rows are transferred to the new tour. - Each confirmed staff member and vehicle is carried over as a draft assignment on the new tour, provided they are available. If a resource is unavailable on the new date, the assignment is silently skipped so the auto-optimizer can fill the gap. - Equipment check-outs are released from the old tour and re-created on the new one. - The original tour is cancelled with an auto-generated note (e.g. "Rescheduled to July 15, 2026"). - A reschedule notification email is sent to every confirmed staff member. - The auto-assignment orchestrator runs on the new tour to fill any gaps left by unavailable resources.

5. Product Catalog

The Products section (admins only) is where you create and manage tour templates. Templates define the product details (duration, pickup, route) and the resource scaling rules that determine what staff and vehicles are needed.

Creating a Template

  1. Go to Products in the sidebar.
  2. Click "New Template" and fill in:
  3. Name — e.g., "Gamboa Rainforest Expedition"
  4. Tour Code — optional code from your manifest CSV (e.g., "GAM-01")
  5. Duration — in hours (e.g., 4.5)
  6. Pickup Time — default pickup time
  7. Pickup Address — e.g., "Hotel lobby"
  8. Transit Duration — minutes from pickup to destination
  9. Click "Save & Add Rules".

Once saved, you will be taken to the template detail page where you can define resource rules.

Template List

The catalog index shows all your templates with pagination. Page navigation appears at the bottom of the list to help you browse.

Editing a Template

On the template detail page, click "Edit" to modify the product fields.

Min Pax per Language

When your tours carry passengers speaking multiple languages, the system tries to assign guides who can cover all languages. If no single guide speaks all languages, the system normally assigns one additional guide per additional language.

The Min Pax per Language field lets you set a threshold: a secondary language only triggers an additional guide if at least that many passengers speak it. Set it to 0 (the default) to always assign guides per language.

Example: If you set it to 20 and a tour has 30 English, 10 French, and 10 Dutch passengers, the system will assign a single guide who speaks English. The French and Dutch groups are too small to justify a dedicated guide.

Price per Pax

The Price per Pax field sets a default price per passenger for tours created from this template. When you create a new tour, this value is automatically pre-filled from the template. You can still override it on each individual tour.

Single-day templates require Price per Pax. If you leave this field empty on a single-day template, the system will not allow you to save it. Multi-day templates do not require this field — their price is derived from the sum of day-plan prices.

Deleting vs Disabling a Template

When you delete a template: - If the template has no active tours or assignments, it is permanently removed. - If the template has active tours or historical assignments, it is disabled instead of deleted. A "Disabled" badge appears next to its name, and it will no longer appear in the product catalog or the tour creation dropdown. - You can re-enable a disabled template at any time by clicking the Enable button on its detail page. This restores it to the catalog.

Multi-Day Templates

To create a tour that spans multiple days, set the template Category to Multi-Day Package when creating a new template.

The template creation wizard then adapts:

  1. Step 1 (Type) — Select Multi-Day Package.
    The wizard hides single-day fields (duration, pickup time, etc.) and shows day-plan management instead.
  2. Step 2 (Basics) — Enter the name and code as usual.
  3. Step 3 (Day Plans) — Add day plans by selecting an existing single-day template for each day. You can reorder plans and optionally override the pickup time or pickup address for each plan.
  4. Step 4 (Pricing) — Skipped for multi-day templates; the price is derived from the sum of each day plan's single template price.
  5. Step 5 (Review) — Review and save.

Each day plan produces one child tour when a multi-day tour is created from this template. The total suggested price is automatically calculated as the sum of all day plan prices.

6. Fleet Management

The Fleet section (admins only) is where you manage all your vehicles — buses, vans, boats, and more.

Adding a Vehicle

Click "Add Vehicle" and fill in:

  • Name — e.g., "Bus 01" or "Panga 3".
  • Main Category — choose Road (buses, vans) or Marine (boats, pangas).
  • Sub-Category — e.g., bus, van, panga, catamaran.
  • Capacity — how many passengers it can carry.
  • Registration Number — license plate or hull ID.
  • Required License — what license the driver or captain must have (e.g., "bus" license for a bus).
  • Ownership — is this vehicle Owned by your agency or Contracted from a third party? This is used in the Payable Report to distinguish between owned vs contracted vehicle costs.
  • Preferred Operator — the default driver (for road vehicles) or captain (for marine vehicles) that should be suggested whenever this vehicle is assigned. Only staff who hold the correct license and role are shown in the list.
  • Hourly / Daily Cost — for cost tracking.

Setting a Preferred Operator

When editing a vehicle, you can select a Preferred Operator from a dropdown. This staff member will be the first suggestion when the system or a dispatcher assigns this vehicle to a tour.

  • For road vehicles, you can only select staff who are certified as drivers and hold the needed license.
  • For marine vehicles, you can only select staff who are certified as captains and hold the needed license.

If the preferred operator is unavailable (on vacation, already assigned elsewhere), the system will pick another available operator automatically.

Maintenance & Unavailability

To take a vehicle out of service:

  1. Go to the vehicle's Edit page.
  2. Scroll to the Maintenance Schedules section.
  3. Click "Schedule New Maintenance".
  4. Set the start and end date/time, and a reason (e.g., "Oil change").
  5. The vehicle will automatically be marked unavailable during that period.

Vehicles in maintenance will not appear in the Fleet Status as available, and the optimizer will skip them.

Deleting vs Disabling a Vehicle

When you remove a vehicle: - If the vehicle has no historical assignments, it is permanently deleted. - If the vehicle has past assignments or is currently assigned, it is disabled instead of deleted. A "Disabled" badge appears in the fleet list, and the vehicle will no longer appear as available for new tours or in the Fleet Status panel on the dashboard. - You can re-enable a disabled vehicle at any time from its edit page by clicking the Enable button.

Importing Vehicles from a CSV

You can bulk-import vehicles by clicking "Import" and uploading a CSV file. The file must contain at least a name and capacity column. Optional columns include category, registration, costs, and license.

7. Team Management

The Team section (admins only) lets you manage your staff.

Roles

Role Permissions
Admin Full access — can manage fleet, team, products, and settings
Dispatcher Can schedule tours, assign staff, process manifests, manage inventory
Guide Can view assignments and the calendar, but cannot make changes

Inviting a New Team Member

  1. Go to Team and click "Invite Member".
  2. Fill in:
  3. Email address — the invitation will be sent here.
  4. First and Last Name.
  5. WhatsApp Number — optional. Includes an international country flag selector (e.g. 🇵🇦 +507 Panama, 🇺🇸 +1 USA, 🇲🇽 +52 Mexico, 🇨🇷 +506 Costa Rica, 🇨🇴 +57 Colombia, 🇪🇸 +34 Spain, 🇧🇷 +55 Brazil, 🇦🇷 +54 Argentina, 🇨🇱 +56 Chile, 🇵🇪 +51 Peru, 🇬🇧 +44 UK, 🇩🇪 +49 Germany, 🇫🇷 +33 France, 🇳🇱 +31 Netherlands). If the user has already populated their WhatsApp number on their personal profile settings, it will display automatically. Adding or updating it here syncs to their user profile.
  6. Role — admin, dispatcher, or guide.
  7. Employment Type — employee, freelance, or contractor.
  8. Languages — what languages they speak (used for auto-assignment).
  9. Operator Licenses — what vehicles they are licensed to drive or captain.
  10. Staff Roles — what dispatch roles they can fill (lead guide, guide, driver, captain).
  11. Click Send Invitation.

The invitation expires after 7 days. You can cancel a pending invitation at any time.

Bulk Invite

You can upload a CSV file to invite many people at once. The file must contain at least an email and role column. You can also include optional first_name, last_name, whatsapp, employment_type, languages, licenses, and staff_roles columns.

Editing a Team Member's Profile

Click on a member's name or Manage to edit their certifications, employment type, rates, and WhatsApp phone number (with country flag code dropdown). This is important because the auto-assignment system uses this information to match the right person to each tour.

Languages

Set a team member's languages (e.g., English, Spanish, French). The auto-assignment system matches these languages against the passenger manifest languages. For example:

  • If a tour has passengers who speak English and French, the system will first look for a guide who speaks both languages.
  • If no bilingual guide is available, it will assign two guides — one for each language.
  • A staff member with no languages set is considered flexible and can be assigned to any tour.

Operator Licenses

Set what licenses a team member holds (e.g., "bus", "van", "panga"). The system checks these when assigning drivers or captains to specific vehicles.

Staff Roles

Mark what dispatch roles a team member can perform: lead guide, guide, driver, captain. This determines what kind of assignments they can receive.

Driving Hours Compliance

For team members with Driver or Captain roles, you can set daily and weekly driving hour limits. These fields only appear after you check the Driver or Captain box.

  • Max Hours per Day — the maximum total working hours this person can accumulate in a single day (e.g., 10).
  • Max Hours per Week — the maximum total working hours for a rolling 7-day week (e.g., 48).

When these limits are set, the auto-assignment system checks the driver's cumulative hours before suggesting them for a tour. If assigning them would exceed the limit, the system skips them and selects the next available operator instead — even if they are the preferred operator for a vehicle.

This ensures compliance with local driving-hour regulations (e.g., EU drivers' hours rules, FMCSA hours of service). Leave both fields blank to disable the check (no limit enforced).

Setting Unavailability (Time Blocks)

Staff members can block off time when they are not available. Go to Settings > My Availability and add a time block with a reason (vacation, appointment, etc.). The auto-assignment system will skip them during that period.

Pausing / Reactivating a Membership

At the end of a season, admins and dispatchers can pause a team member's membership instead of removing them. Pausing:

  • Excludes the member from auto-assignment suggestions.
  • Keeps their profile, certifications, and settings intact.
  • Shows them as "Paused" in the team list.

To pause, click Pause next to the member's name in the team list.

To reactivate, click Reactivate (admins and dispatchers only). The system sends a notification email letting the member know their membership has been reactivated.

Re-inviting a paused member: If you try to send an invitation to an email that already has a paused membership, the system automatically reactivates the existing membership and notifies the user — no new invitation is created.

8. Dispatch & Assignments

Manual Assignment

From the Dispatch page, each tour card includes a dynamic manual assignment form to add staff or vehicles:

  1. Staff Selection: Select a staff member from the Staff dropdown. The list displays the person's First Name + Last Name and their certified dispatch capabilities (e.g., Noah UIOne (Driver / Guide)).
  2. Smart Default Role Pre-selection: Upon selecting a staff member, the Role dropdown automatically pre-selects their primary certified role (Driver, Captain, Lead Guide, or Guide) and filters valid options based on their registered capabilities.
  3. License & Category Vehicle Matching:
  4. Driver: Enables the Vehicle dropdown and filters exclusively to Road vehicles (Bus, Van, Midi Coach, etc.) that match the driver's operator licenses.
  5. Captain: Enables the Vehicle dropdown and filters exclusively to Marine vehicles (Panga, Catamaran, Skiff, etc.) that match the captain's marine licenses.
  6. Guide / Lead Guide: Automatically disables the Vehicle dropdown with "(No vehicle needed)".
  7. Vehicle dropdown options display capacity and category details (e.g., Coaster Bus 01 (30 pax · Road)).
  8. Assigned & Overlapping Resource Exclusions: Staff members and vehicles already assigned to the current tour or to another overlapping tour on the same date are automatically excluded from the selection dropdowns.
  9. Real-Time Live Dropdown Auto-Refresh: Clicking + Assign or removing an assignment automatically updates the manual assignment form in real-time via Turbo Streams without requiring a page reload. Assigned staff/vehicles disappear immediately upon assignment and re-appear if an assignment is removed.
  10. Interactive Pre-Submit Rule Validation Warnings & Confirmations:
  11. Oversized Vehicle Warning: If you select a vehicle with 40+ capacity for a small group (e.g., 8 passengers) when a smaller suitable vehicle (e.g., a 15-pax van) is available in your fleet, or if an under-capacity vehicle is chosen, an interactive warning prompt alerts you before submitting: > "Warning: This tour has 8 passengers, but you selected 'Custom Big Bus' (50 pax capacity) when a smaller suitable vehicle is available. Are you sure you want to proceed?"
  12. Guide / Staff Requirement Over-Assignment Warning: If template rules specify required guide counts (e.g., 1 Lead Guide required) and that requirement is already fulfilled, attempting to assign an additional guide triggers a confirmation dialog: > "Rule Override Confirmation: The tour template rules specify 1 LEAD GUIDE(s), which are already assigned (1 currently assigned). Are you sure you want to assign an additional LEAD GUIDE and override the rule?" Clicking Cancel stops the submission; clicking OK confirms the manual rule override.

Removing an Assignment

You can remove an assignment by clicking the Remove button next to it. This is not allowed once the tour has started. Removing an assignment instantly restores the staff member and vehicle back into the manual assignment dropdown options.

Assignment Statuses

  • Draft — proposed by the auto-assignment system, pending your review. No notification is sent.
  • Confirmed — the assignment is active. The staff member receives a notification by email, Telegram, or WhatsApp (depending on their agency's enabled notification channels). They can Accept the assignment by clicking the link in the email or tapping the inline Accept button in Telegram or WhatsApp.
  • Rejected — the assignment was declined. This is kept for audit purposes.

Accepting Assignments (for Staff)

When you are assigned to a tour: 1. You receive a notification by email, Telegram, and/or WhatsApp with tour details. 2. Via email: Click the "Accept Assignment" button in the email — you will see a summary of the tour. Click Accept. 3. Via Telegram or WhatsApp: Tap the "✅ Accept" button on the notification message — the bot/service confirms your acceptance. 4. A confirmation email is sent to you with a calendar invite (.ics) you can add to Google Calendar, Outlook, or Apple Calendar. 5. Your dispatcher sees a live notification that you accepted.

Compensation Type

Each assignment tracks whether the staff member is paid on a Gig (flat fee per tour) or Hourly basis. The compensation type is inherited from the tour's default setting but can be overridden per assignment.

  • Freelance staff show a purple Freelance badge next to their name. Dispatchers and admins can click the ⏱ Hourly or 💰 Gig badge to toggle the compensation type for that assignment.
  • Employees and contractors do not show the compensation badge — their compensation is managed through your agency's payroll system.

9. Auto-Assignment & Optimization

PragmaticTours can automatically suggest the best combination of vehicles and staff for your tours. This saves time and helps you use your resources efficiently.

Optimizing a Single Tour

On any tour card, click "Auto-Assign". The system will:

  1. Analyze your fleet — check which vehicles are available (not in maintenance, not already assigned elsewhere).
  2. Select the best vehicles — it picks vehicles that have enough seats for your passengers, while using the fewest vehicles possible and minimizing wasted seats.
  3. Select the best staff — based on:
  4. Required roles (lead guide, guide, driver, captain).
  5. Language coverage — staff languages are matched to passenger languages from the manifest.
  6. Licenses — drivers and captains must hold the correct license for the vehicle.
  7. Availability — no time-off blocks or scheduling conflicts.
  8. Preferred operator — if a vehicle has a preferred driver or captain, they are suggested first.

Example: You have a tour with 20 passengers who speak English and French. Your fleet has one bus (40 seats), one van (15 seats), one panga (10 seats), and another panga (10 seats). You have one bilingual lead guide who speaks English and French, and one English-only guide.

The system will: - Suggest the van (15 seats) + one panga (10 seats) = 25 total seats, instead of using the bus (40 seats) which would waste 20 seats. - Suggest the bilingual lead guide for both languages, instead of assigning two separate guides.

Optimizing an Entire Day

On the Dispatch page, click "Optimize Day". The system analyzes ALL tours on that date and proposes assignments across all of them, making sure: - Each vehicle is only used on one tour per day. - Each staff member is only assigned to one tour at a time.

This is useful when you have multiple tours on the same day and want the best overall use of your fleet and staff.

Reviewing Proposals

All auto-assignments are created as Draft — nothing is final until you approve it. You will see a panel with all proposed assignments:

  • Accept each proposal individually, or use "Accept All" to confirm everything at once.
  • Reject proposals that don't work for you.
  • Once accepted, the assignment becomes Confirmed and notifications are sent.

Important Notes

  • Auto-assignment is a suggestion tool. You can always override it by making manual changes.
  • The system never assigns a vehicle or person that is blocked by maintenance or has a scheduling conflict.
  • If no solution is found (e.g., not enough vehicles for all tours), the system will propose what it can and leave the rest for manual assignment.
  • If a tour template has no resource rules defined, the system cannot auto-assign anything for that tour. It will show a warning message: "No resource rules defined on this template. Please add rules or assign manually." Define rules in the template's detail page or assign staff and vehicles manually.

Optimization Modes: Resources vs Cost

The system offers two optimization modes. You will see two sets of buttons on the Dispatch page:

Button Mode Goal
⚡ Auto-Assign / ⚡ Optimize Day / ⚡ Optimize Multi-Day Minimize Resources (default) Use the fewest vehicles and staff possible, with least wasted seats.
💰 Auto-Assign (Cost) / 💰 Optimize Day (Cost) / 💰 Optimize Multi-Day (Cost) Minimize Cost Use the cheapest combination of vehicles and staff that meets all requirements.

Both modes respect all the same constraints — availability, licenses, hours, language coverage, and resource rules. The only difference is how choices are made among candidates that pass every filter.

Staff continuity vs. cost: When optimizing a multi-day tour, staff continuity always wins over cost. The tiebreaker hierarchy is: 1. Language/role score 2. Was this person assigned on a previous day of the same multi-day tour? (preferred) 3. Staff cost (cost mode only) 4. Hours worked that day 5. Name (alphabetical)

This means if the cheapest guide for Day 2 is a different person than Day 1's guide, the system will keep the Day 1 guide — continuity is prioritized over saving money. Cost optimization only affects which guide is chosen when there is no continuity preference (e.g., first day of a multi-day tour, or a single-day tour).

When to Use Each Mode

  • Minimize Resources — Use when you want to keep your fleet usage low and avoid dispatching more vehicles than necessary. Best when vehicle availability is tight and you need to reserve capacity for other tours.
  • Minimize Cost — Use when you have a variety of vehicle and staff options at different price points and want to minimize payout costs. A small cheap van may be preferred over a large luxury bus, even if it means using more than one vehicle.

How Cost Optimization Works

Vehicles: Each vehicle's total cost is the greater of hourly_cost × tour_duration and daily_cost (whichever is higher). The cost per seat is then total_cost ÷ capacity. The system picks vehicles with the cheapest seats first, regardless of size. This means it might choose two small cheap vans over one large expensive bus if the vans are cheaper per passenger, and it respects the vehicle's daily minimum cost even if the tour is short.

Staff: Staff cost is calculated as: - Gig rate (flat fee per tour) for gig-based compensation. - Hourly rate × tour duration for hourly-based compensation.

Among candidates with equal language coverage and role qualifications, the cheapest staff member is chosen first.

Example: You have a tour with 20 passengers. Your fleet options are: - Bus A: 50 seats, $100/hr ($2.00 per seat per hour) - Bus B: 30 seats, $80/hr ($2.67 per seat per hour) - Van: 15 seats, $50/hr ($3.33 per seat per hour)

In Resources mode, the system picks the smallest sufficient vehicle (Van + Bus B = 2 vehicles, minimal waste). In Cost mode, the system picks the cheapest seats first (Bus A alone — $2.00/seat is cheapest, even though it's the largest).

Conflict Resolution & Tie-Breaking Priority

When multiple staff members could fill a role, the system resolves conflicts using the following decision hierarchy. Each step narrows the pool until only one candidate remains.

For Guides (Lead Guide & Guide)

Priority Rule What Happens
1 Language coverage Staff whose spoken languages overlap with the tour's required languages are preferred. A staff member with no languages set is treated as flexible — they can be assigned but are not chosen over someone with a documented language match.
2 Lead-guide qualification When looking for a universal guide (someone who speaks ALL required languages), a person who can act as lead guide is preferred over one who can only guide.
3 Hours worked Among equally qualified candidates, the one with fewer hours already assigned on that day is chosen. This distributes workload evenly and avoids pushing anyone into overtime.
4 Name (alphabetical) As a final deterministic tie-breaker, the staff member whose name comes first alphabetically is chosen.

For Drivers & Captains

Priority Rule What Happens
1 License match The staff member must hold the correct operator license for the vehicle. Staff without the required license are excluded entirely.
2 Hours compliance Staff who would exceed their max_daily_hours or max_weekly_hours are excluded, even if they are the preferred operator.
3 Preferred operator If the vehicle has a preferred_operator_id and that person is available, licensed, and within hours, they are assigned immediately.
4 Hours worked Among remaining candidates, the one with fewer hours assigned that day is chosen.
5 Name (alphabetical) Final deterministic tie-breaker.

For Vehicles

Priority Rule What Happens
1 Fewest vehicles The system first minimizes the total number of vehicles needed (CP-SAT solver) or uses best-fit bin packing (greedy fallback).
2 Least wasted capacity Among solutions with the same number of vehicles, the one with the smallest total capacity (least empty seats) is chosen.

Cost Mode Tie-Breaking

When you use the 💰 Minimize Cost mode, the tie-breaking rules above change at two levels:

Vehicles: Instead of minimizing vehicle count and wasted capacity, the system minimizes total monetary cost (hourly_cost × tour_duration). It may choose more vehicles if they are collectively cheaper.

Staff (guides, drivers, captains): After language coverage, a new tie-breaker is inserted:

Priority Rule What Happens
3 Staff cost (cost mode only) Among equally qualified candidates, the one with the lower staff cost (gig rate or hourly rate × duration) is chosen.

This means the full guide priority in cost mode becomes: language coverage → lead-guide qualification → staff cost → hours worked → name. And the full operator priority becomes: license → hours → preferred operator → staff cost → hours worked → name.

What Happens When No One Is Available

If no eligible staff member can be found (all are over hours, all lack licenses, all already assigned), the system records a failure in the optimization result and leaves that slot empty for manual assignment. You will see these failures listed in the optimization results panel.

Day-Scope Protection

When you run "Optimize Day", the system tracks every staff assignment across all tours on that date. A staff member assigned to the morning tour will not be proposed for the afternoon tour if there's a time overlap, even if each tour individually would consider them available. This prevents double-booking across your entire day.

Language Validation

When a staff member is assigned to a tour (either by the optimizer or manually), the system verifies that the assigned staff member's spoken languages overlap with at least one of the tour's passenger languages. If the staff member has languages set but none match the tour, the assignment is rejected with an error message. This ensures that a bilingual tour never gets an English-only guide.

This validation does not apply to staff with no languages set (they are considered flexible) or to non-guide roles (drivers, captains).

Optimizing a Multi-Day Tour

If you have a multi-day tour (with multiple daily child tours linked to a parent), you can optimize all days at once. On the parent tour card, next to the "Multi-Day (X days)" badge, you will find:

  • ⚡ Optimize Multi-Day — Runs resource-minimizing optimization on every child tour of the multi-day parent.
  • 💰 Optimize Multi-Day (Cost) — Runs cost-minimizing optimization on every child tour.

When you click either button, the system: 1. Optimizes each child tour independently, following its own template's resource rules. 2. Prefers the same staff (guides, drivers, captains) across consecutive days when they are available, providing consistency for your guests. 3. Collects all proposals into a single parent panel grouped by day.

This is more efficient than optimizing each day individually, especially for tours spanning 3+ days where you want the same guide throughout.

Understanding Unmet Requirements

When the system cannot fulfill every requirement, it records the failures and displays them as a warning banner at the top of the draft proposal panel. For example:

⚠️ Some requirements could not be met - Driver for Mercedes 500 1: No available driver (licensed, within hours, not already used) - Captain for Ocean Panga Boat: No available captain (licensed, within hours, not already used)

These warnings appear when: - No staff member with the required role is available on that date (scheduling conflicts, time-off blocks). - No staff member has the correct license for the vehicle. - All candidates would exceed their daily or weekly hour limits. - There are not enough qualified people for the number of vehicles (e.g., 2 pangas but only 1 captain).

The unfilled slots are left empty for manual assignment. You can use the manual assignment form below the draft panel to add staff or vehicles yourself.

10. Passenger Manifests

You can upload passenger lists in CSV format. The system supports two formats:

Cruise Format

Typically used for cruise ship passengers coming ashore for tours. Columns may include: - Voyage number, ship name, tour code, passenger names, language, special needs.

Charter Format

Typically used for private charters or group bookings. Columns may include: - Flight number, tail number, total passengers, connecting tour code.

How to Import

  1. Go to Manifests and click "Upload Manifest".
  2. Select your CSV file. Optionally, set a Schedule Date if the file does not include dates.
  3. The system will process the file and show you:
  4. Valid rows — passengers that match an existing tour template.
  5. Invalid rows — passengers that could not be matched (e.g., unknown tour code).
  6. Resolve invalid rows by either:
  7. Assign to an existing template — select a tour product from the dropdown next to the row and click "Assign". The row immediately becomes valid.
  8. Create a new product — click "+ Create Missing Product" to open a new template form in a new tab, pre-filled with the missing code. After saving, click "Re-validate" to re-process the file.
  9. You can also skip invalid rows — the Import button is always available when there are valid rows. Invalid rows are simply ignored. A note shows how many will be skipped.
  10. Click "Import". The system will create tours and assign passengers to them based on the passenger counts.

Per-Tour Upload

You can also upload a manifest directly on a specific tour page. This is useful when you already know which tour the passengers belong to.

11. Equipment & Inventory

Warehouses

Create warehouses to store your equipment. Each warehouse has a name and address.

Adding Equipment

Go to Inventory and click "Add Item". Enter: - Name — e.g., "Snorkel Sets". - Warehouse — where it is stored. - Total Quantity — how many you have. - Notes — any additional information.

Deleting vs Disabling an Asset

When you remove an asset from inventory: - If the asset has no usage history or template rules, it is permanently deleted. - If the asset has usage history or is referenced by template rules, it is disabled instead. A "Disabled" badge appears in the inventory list, and the asset will no longer appear in checkout suggestions. - You can re-enable a disabled asset at any time from its detail page.

Checking Out Equipment

On a tour card, click to add equipment. Select the item and enter the quantity your team is taking. The available quantity will decrease automatically.

Checking In Equipment

When your team returns, log the quantity returned. If everything comes back, the available quantity is restored. If some items are missing, the system will send an alert to the admins and dispatchers.

Auto-Suggested Equipment

If your tour templates have equipment rules set up (e.g., "1 snorkel set per 2 passengers"), the system will suggest the right quantities when you open a tour.

12. Financial Reports

The Reports section (admins only) shows daily revenue, staff costs, vehicle costs, and net profit for your tours.

Accessing Reports

  1. Click Reports in the sidebar (admins only).
  2. By default, the current month is shown. Use the Previous Month / Next Month arrows to navigate.
  3. For a custom date range, use the From and To date pickers and click Filter.

Report Columns

Column Description
Date The tour date.
Tour The tour name.
Pax Number of passengers.
Price/Pax Price per passenger set on the tour.
Revenue Price/Pax × Pax (tour revenue).
Staff Cost Sum of staff assignment costs for the tour.
Vehicle Cost Sum of vehicle costs for the tour.
Net Revenue - Staff Cost - Vehicle Cost.

How Cancelled Tours Affect Reports

Cancelled tours are included in the Financial Report — they appear with a "Cancelled" badge, and all their values (Revenue, Staff Cost, Vehicle Cost, Net) are shown as $0.00 / —. This prevents cancelled tours from distorting the report with misleading revenue or profit calculations.

Note: Since revenue is set to $0.00, a cancelled tour that had confirmed assignments before cancellation does not inflate the report's totals. The Payable Report excludes cancelled tours entirely.

Exporting to CSV

Click the CSV button to download the current report as a CSV file, which you can open in Excel, Google Sheets, or any spreadsheet application. The CSV includes a total row at the bottom.

CSV Format: Columns are Date, Tour, Pax, Price/Pax, Revenue, Staff Cost, Vehicle Cost, Net — one row per tour, plus a final TOTAL row. Compatible with Excel, Google Sheets, QuickBooks, Xero, and most accounting software.

13. Payable Report

The Payable Report (admins only) shows a detailed breakdown of what needs to be paid — freelance staff compensation and vehicle costs — for a given period.

Accessing

Click Payable Report in the sidebar (admins only). By default, the current month is shown.

What's Included

  • Freelance staff — only freelancers are listed (employees and contractors are excluded since their compensation is handled through payroll). Shows the compensation method (Gig or Hourly), the rate, the hours worked (tour duration), and the total cost.
  • Vehicles — all vehicles assigned to tours are listed with their hourly cost, hours used, and total cost. The Ownership column indicates whether the vehicle is Owned by your agency or Contracted from a third party.

Columns

Column Description
Date The tour date.
Tour The tour name.
Name Name of the freelance staff member or vehicle.
Type Staff (Gig/Hourly) or Vehicle.
Rate Hourly or Gig rate for staff; hourly cost for vehicles.
Hours Tour duration in hours (— for Gig-based staff).
Total Rate × Hours (or flat Gig rate).
Ownership Owned or Contracted (vehicles only).

Exporting to CSV

Click the CSV button to download the report for any date range.

CSV Format: Columns are Date, Tour, Name, Type, Rate, Hours, Total, Ownership — one row per freelance staff assignment or vehicle assignment. Compatible with Excel, Google Sheets, QuickBooks, Xero, and most accounting/ payroll software.

What is included: Only confirmed assignments are included. Draft or rejected assignments are excluded. If a tour is cancelled after its assignments were confirmed, those assignments are set to cancelled status and will not appear in the Payable Report. This prevents paying for cancelled work.

14. User Settings

User Settings are personal workspace settings accessible to all staff members by clicking your initials/avatar in the top-right bar of the user dropdown menu:

Profile Settings (/settings/profile)

  • Update your First Name and Last Name.
  • Choose your Preferred Interface Language (English, Spanish, Portuguese, French, or Dutch).
  • Manage your Contact Numbers (Cell phone, WhatsApp number with international country flag selector).

Telegram Connection (/settings/telegram)

(Only visible when Telegram notifications are enabled by your agency) 1. Click Connect to Telegram to generate a unique pairing link (e.g., https://t.me/MyAgencyBot?start=ABC123). 2. Send the link to your agency's Telegram bot. 3. Once linked, you will receive real-time assignment notifications with inline ✅ Accept / ❌ Decline buttons.

WhatsApp Connection (/settings/whatsapp)

(Only visible when WhatsApp notifications are enabled by your agency) 1. Click Generate Pairing Code to produce a 6-digit code or direct wa.me connection link. 2. Send the code to your agency's registered WhatsApp Business number. 3. Once verified, a green Connected badge appears showing your phone number. 4. Click Send Test Message to verify message delivery.

Change Password (/settings/password)

Update your login password by entering your current password followed by your new password.

Availability Settings (/settings/availability)

Set personal time-off blocks (vacations, medical appointments, personal days). These blocks automatically prevent the auto-assignment system from scheduling you on those dates.

Agency Switcher & New Agency Setup

  • If your account belongs to multiple tour agencies, click any agency name in the dropdown to instantly switch workspaces.
  • Click + Create New Agency to set up a new agency workspace under your user account.

15. Account Settings

Account Settings (Agency Administration) are accessible only to Admins via Settings in the left sidebar navigation (/settings/account).

Agency Information & Subscription Plan

  • Update your official Agency Name.
  • View current Subscription Plan tier, billing cycle, and feature limits.

Notification Channels

Enable or disable agency notification dispatch channels: Email, Telegram, and WhatsApp. Multiple channels can be active simultaneously depending on your plan.

Telegram Bot Configuration

  1. Create a Telegram bot via @BotFather and obtain its API token.
  2. Enter the Bot Token and Bot Username.
  3. Click Register Webhook to connect the bot to PragmaticTours.

WhatsApp Cloud API Configuration

  1. Connect with Meta (Embedded Signup): Click Connect with Meta to authorize your WhatsApp Business Account (WABA).
  2. Manual Configuration: Enter your Permanent Access Token, Phone Number ID, and WABA ID.
  3. Centralized Webhook Policy: Webhook URL, App Secret, and Webhook Verify Token are managed centrally at the platform infrastructure level.

WhatsApp Message Templates Management

When WhatsApp is enabled for your agency, admins manage Meta message templates from Settings > Account Settings (/settings/account):

1. Meta Template Categories & Advantages

Meta classifies all message templates into three distinct categories. Selecting the right category affects review speed, messaging costs, and deliverability:

Category Purpose & Content Advantages & Differences
UTILITY Transactional, operational messages directly tied to an active booking, assignment, cancellation, or account link (e.g. tour assignments, reschedules, cancellations). • Fast Review: Approved within minutes by Meta's automated systems.
• Lower Cost: Lower messaging rate tier per conversation.
• High Reliability: Extremely low risk of user block or spam reports because messages are purely operational.
• No Opt-Out Mandate: Does not require marketing opt-out buttons.
MARKETING Promotional messages, special offers, new tour announcements, seasonal packages, or customer re-engagement campaigns. • Content Flexibility: Allows promotional language, discounts, call-to-action sales buttons, and marketing pitch copy.
• Higher Cost: Higher pricing tier per conversation.
• Stricter Review: Subject to stricter Meta content reviews and higher user report rates if sent unprompted.
AUTHENTICATION One-time passcodes (OTP) and security verification codes for multi-factor login verification. • Security Standardized: Purpose-built for security codes with instant copy-code buttons.

2. System Events & Notification Triggers

PragmaticTours automatically dispatches WhatsApp messages when specific system events occur:

System Event Mapped template_type Trigger Condition Positional Variables & Content Interactive Buttons
Tour Assignment tour_assignment Triggered automatically when a dispatcher or auto-assigner confirms a staff member assignment to a scheduled tour. {{1}} Tour Name
{{2}} Pickup Date & Time
{{3}} Pickup Address		 Interactive ✅ Accept / ❌ Decline buttons
Tour Cancellation tour_cancellation Triggered automatically when an admin or dispatcher cancels a scheduled tour. {{1}} Tour Name
{{2}} Date
{{3}} Cancellation Reason		 None
Tour Reschedule tour_reschedule Triggered automatically when a tour is rescheduled to a new date/time. {{1}} Tour Name
{{2}} Old Date
{{3}} New Date & Pickup Time		 None
WhatsApp Linking whatsapp_linked Triggered when a staff member successfully links their WhatsApp account. {{1}} Staff Member Name
{{2}} Agency Name		 None
Chat Reply chat_reply Triggered during interactive chat exchanges between staff and the WhatsApp service. {{1}} Response Message None

3. Meta Formatting & Approval Requirements

  • All WhatsApp templates must be reviewed and approved by Meta before they can be used to send outbound messages.
  • Positional variables must start at {{1}} and increase sequentially ({{1}}, {{2}}, {{3}}).
  • Mandatory sample values must be provided for every variable.

4. Creating Default Templates

  • Select a language and click Create Default Templates to submit pre-formatted standard templates (tour_assignment_v1, tour_cancellation_v1) to Meta.

5. Creating Custom Templates & Mapping System Events

  • Expand Create New Template under Settings > Account Settings.
  • Template Name: Unique lowercase string accepted by Meta (e.g. caribbean_adventure_invite_2026).
  • System Event / Purpose: Select the target system event from the dropdown (e.g. Tour Assignment). This maps your custom Meta name directly to internal system triggers (template_type: "tour_assignment").
  • Body & Variables: Enter message text using sequential positional variables ({{1}}, {{2}}, {{3}}).

6. Overwriting & Custom Template Lifecycle

  • Once Meta approves the custom version (status 🟢 APPROVED), PragmaticTours automatically switches to using the latest approved template version for all subsequent outbound notifications.

API Keys (Admins Only)

Admins can generate API keys to allow external systems to interact with your PragmaticTours data programmatically via Settings > API Keys (/api_keys).

Account Cancellation & Data Export

Any workspace member can request account cancellation from Settings (/settings/account). Scroll to Cancel Account: - Triggers a complete CSV data export (profile, tours, passengers, vehicles, assignments). - Grants a 60-day grace period during which you retain access and can restore your workspace or download your data export.

16. API Reference (v1)

PragmaticTours provides a REST API for external systems (CRMs, booking platforms, custom integrations) to manage tour data programmatically. All endpoints return JSON.

Authentication

Every request must include an API key in the Authorization header:

Authorization: Bearer pt_your_api_key_here

Generate API keys at Settings > API Keys in your dashboard.

Base URL

https://youragency.pragmatictours.com/api/v1

Endpoints

Method Path Description
GET /api/v1/tours List tours (with optional filters)
GET /api/v1/tours/:id Get a single tour with full details
POST /api/v1/tours Create a new tour
GET /api/v1/me Check session status (used by mobile app)

List Tours

GET /api/v1/tours

Optional query parameters:

Param Type Description
from date Filter by date range start (e.g. 2026-08-01)
to date Filter by date range end
template_id integer Filter by tour template
status string Filter by status (scheduled, in_progress, completed, cancelled)

Example:

curl -H "Authorization: Bearer pt_your_key" \
  "https://youragency.pragmatictours.com/api/v1/tours?from=2026-08-01&to=2026-08-31"

Get a Tour

GET /api/v1/tours/:id

Returns the tour with all fields. Multi-day tours include a child_tours array.

Create a Tour

POST /api/v1/tours
Content-Type: application/json

Single-day example:

{
  "tour": {
    "tour_template_id": 3,
    "pax_count": 20,
    "date": "2026-08-20",
    "pickup_time": "08:00",
    "pickup_address": "Hotel Lobby",
    "transit_duration_minutes": 30,
    "price_per_pax": 75.0
  }
}

Multi-day example (creates child tours automatically from template plans):

{
  "tour": {
    "tour_template_id": 7,
    "pax_count": 15,
    "start_date": "2026-09-10",
    "end_date": "2026-09-13"
  }
}
Field Single-day Multi-day Auto-filled from template
tour_template_id Required Required —
pax_count Required Required —
date Required — —
start_date — Required —
end_date — Required —
pickup_time Optional — Yes
pickup_address Optional — Yes
transit_duration_minutes Optional — Yes
price_per_pax Optional — Yes
category Optional Optional Auto-detected from template
compensation_type Optional — Defaults to gig

Error Responses

Status Meaning
400 Bad request — missing required parameter
401 Unauthorized — missing or invalid API key
404 Not found — resource does not exist
422 Unprocessable entity — validation errors

Error bodies contain a JSON object with an error key. Depending on the error type, the value may be a string or an array of strings:

  • 400 Bad Request: { "error": "param is missing" } (string)
  • 401 Unauthorized: { "error": "Invalid or revoked API key" } (string)
  • 422 Validation Error: { "error": ["Tour template is required", "Pax count must be greater than or equal to 0"] } (array)

Need Help?

If you have questions or run into issues, contact your agency administrator. They can manage your account, adjust your permissions, or help you with any workflow questions.