It’s built to be the foundation for reporting across the platform: the place our own exports are delivered, the foundation we’re building richer reporting on, and a surface you can use right now to distribute your own reports within your tenant — a monthly statement to a customer, a compensation summary to a driver, an operations report to your admins — with no bespoke delivery work on your side.

Where to start

The full surface and its concepts live under the Reports tag — visibility grants, the two creation flows, retention and permissions. Start there if you’re integrating.

Publishing a report

Create a report with Create a report in one of two ways:

• 📎 Immediately, by including the file inline — the report is ready to download straight away. Reach for this when you already have the file.
• ⏳ As a pending announcement, when the file is still being generated — create the report first, then finish it with Complete a report once the file is ready, or Fail a report (with an optional reason) if generation didn’t work out.

Either way the report shows up in the list and on its own detail page, giving every recipient a durable, always-available place to find it.

Sharing with exactly the right people

Every report carries visibility grants that decide who can see it — and that’s the whole story, there is no implicit admin-sees-everything. You can share a report with:

• every admin,
• all managers of a specific organization,
• or a single admin, org manager, customer or driver.

Grants combine, so the same report can go to your back office and the one customer it concerns at the same time. This is what makes the API genuinely self-serving: you decide, per report, precisely who it reaches. Set notify_by_email when you create a report and everyone it is shared with gets an e-mail the moment it becomes ready.

Organize and filter with tags

Grants decide who sees a report; tags decide how it’s organized. Every report carries a free-form list of labels you choose, and List reports filters by them — each tag you add narrows the results — so the labels become the axes your recipients navigate by. Pick whatever dimensions matter to you:

• a report type — type:compensation, type:billing, type:operations,
• a time period — 2026-W28, 2026-06,
• a subject — org:1234, region:eu.

And they combine: type:compensation plus 2026-W28 returns exactly one week’s compensation reports. Consistent tags turn a growing pile of reports into something anyone can find their way around at a glance — with no bespoke filtering on your side.

Coming soon

A dedicated Reports section in the dashboard is on its way, giving your team a searchable, filterable view of every report they can see — no API required. The API described here is available today.

This is also the foundation we’re consolidating reporting onto. The existing custom reports our customer success team maintains for you will be migrated gradually to this new platform, and the CSV export features in the web dashboard will soon move over to it too — so more and more of the reports you already rely on will show up here, in one consistent place.

How it works

Whenever a stop is created from a place and no group is provided, it receives an automatic group derived from the stop’s type and the place, of the form A-<type>-<place_id> (for example A-pickup-<place id>). This applies both when creating a booking and when inserting a custom stop:

Create a Booking Insert custom stop into existing tour Insert custom stop into existing booking

Because two stops built from the same place with the same type derive the same group, they line up automatically once they share a tour — and completing the first as a driver completes the rest of the group, exactly as if the group had been set by hand.

When a stop’s type is later changed via Update Stop Properties, its automatic group is updated to match the new type, so grouping stays correct as stops are edited.

Your custom groups are always respected

A group you provide yourself is never touched: if a stop is created with an explicit group, that value is kept, and it is never overwritten when the type changes. The leading A- prefix is what marks a group as automatically managed — any group without it is treated as yours to control, through Bulk Update Stop’s Groups as before.

To accommodate the new format, the maximum length of a stop group has been increased from 40 to 50 characters.

Adopting it smoothly

If you currently assign stop groups yourself — for instance through a customization or an automation scenario — you can now hand that job to the platform. To roll over without clobbering the automatic groups, make your integration set a group only when the stop does not already have one, rather than always writing it. Once the automatic grouping is in place, ordinary stop mirroring keeps groups consistent across the booking and its tour on its own, and the group-setting customization can be retired.

Why this matters

Automatic grouping makes the out-of-the-box behaviour match what operators expect: build bookings from places, stack them into a tour, and the shared stops group and complete as one — no extra configuration, and no race between competing integrations trying to set the same group. It removes a whole class of manual-dispatching and stacking edge cases and cuts the churn of redundant updates that those integrations used to trigger.

The outcomes

Fail stop accepts an optional outcome parameter on tour stops:

• return_now — appends a return stop to the booking, going back to the pickup’s address and contact, and dispatches it right onto the tour the stop failed on.
• return_later — appends the return stop without dispatching it, leaving the dispatcher in control of when and how it goes out.
• reattempt_now — appends a reattempt stop, a full copy of the failed stop, and dispatches it onto the failing tour for an immediate second attempt.
• reattempt_later — appends the reattempt copy undispatched.
• skip_recovery — the stop stays failed and no recovery stop is created. This is the default when no outcome is given, so existing integrations keep working unchanged.

Recovery stops are regular booking stops: they keep the booking active until they reach an outcome of their own, and the failed stop stays in place — the booking’s history reflects every attempt.

Choosing safely

Each outcome has pre-conditions — returns require the return stop type and a pickup-then-drop-off booking shape, “now” variants require the tour to still be active, and stop limits apply. To offer exactly the recovery choices that apply before making the call, tour stop payloads (for example on Show Booking) carry a failure_options object indicating, per outcome, whether the current user may select it.

Each entry pairs an allowed flag with a localized reason explaining why an outcome is currently unavailable (null when it is allowed), ready to be shown to the user as-is:

"failure_options": {
  "outcomes": {
    "skip_recovery":   { "allowed": true,  "reason": null },
    "reattempt_later": { "allowed": true,  "reason": null },
    "reattempt_now":   { "allowed": false, "reason": "The tour for this stop is no longer active." },
    "return_later":    { "allowed": true,  "reason": null },
    "return_now":      { "allowed": false, "reason": "The tour for this stop is no longer active." }
  }
}

The availability reflects everything that determines an outcome’s fate: the user’s role, the stop’s status, the tour’s state, service configuration and capacity, and the booking’s shape. The object renders on tour stops that can currently be failed (approaching or arrived), and only for users that can run stop failure flows: administrators, organization managers and the tour’s driver.

When a chosen outcome is not available after all, the fail request is rejected as a whole with a 422 naming the reason — the stop is not failed in that case. A UI driven by failure_options should rarely see these rejections.

failure_options also replaces the boolean fail indicator inside completion_requirements, which is now deprecated — failure_options.outcomes.skip_recovery.allowed carries the same signal, alongside the richer per-outcome availability.

Webhooks

• booking.stop_failed now carries the applied outcome alongside the failure_reason, so downstream systems no longer need to diff the booking’s stop list to learn what recovery was chosen.
• The new booking.return_started event fires whenever a return stop is dispatched into a tour — the moment goods start moving back.

Why this matters

Together with terminal failed stops, this completes the structured recovery flow: every failure gets an explicit decision, every attempt is a first-class stop, and both the dashboard and your integrations see the same availability rules and the same audit trail.

The rest of the lifecycle follows the same principle:

• When the driver leaves the tour again (ditch, unclaim, claim-window expiry, or revocation), the managing organizations regain visibility.
• A tour that completes or gets cancelled with a driver on it stays with the executing driver’s organization, also in history views — and the managing organizations you configured are no longer rewritten when a tour ends, so the list set via Update managing organizations stays what you set it to.
• Bookings split across several tours are visible to the organizations of all drivers currently executing them.
• Bookings and tours without managing organizations remain invisible to every organization manager while staying open to drivers of all organizations.

Previously, this behaviour required custom automation rewriting the managing organizations during the tour lifecycle; it is now the built-in default for every tenant, with no configuration needed.

Alongside this change we have thoroughly reworked the Booking & Tour Visibility documentation: it now walks through who sees what per role, the full lifecycle rules above, what carries over from bookings to tours on dispatch, and how related features — Linking Organizations to Service Areas, preferred drivers, and the gradual rollout extension — tie into visibility.

The replacement is the new failure_options object on the same stop payloads (for example on Show Booking): failure_options.outcomes.skip_recovery.allowed carries the same signal, and the object additionally indicates the availability of every other recovery outcome together with a localized reason when one is not available.

Until removal, completion_requirements.fail continues to work unchanged. Migrate by reading failure_options.outcomes.skip_recovery.allowed instead — note that failure_options renders on tour stops in failable states (approaching or arrived), so treat an absent object the same as fail: false.

What changes

• A failed stop can no longer be re-dispatched. Creating a new tour from a failed stop via Dispatch stops into a tour now returns a 422 carrying the failed_stops failure code, and inserting a failed stop into an existing tour via Dispatch or move stops into existing tour is likewise rejected — rather than moving the stop back into a tour.
• When every stop on a booking has reached a final outcome — completed or failed — the booking now completes automatically rather than returning to a dispatchable state. If a stop fails while the booking still has stops in progress or waiting to be dispatched, the booking simply carries on with those — a failure no longer pushes the rest of the booking back toward dispatch.
• A failed stop now stays linked to the tour it failed on, rather than being detached from it as before, so the failure remains traceable to where it happened.

What this looks like

Here’s how the change plays out across the situations you might see in the field:

Why this matters

Making failure terminal gives every booking a single, predictable lifecycle: a stop reaches an outcome once and keeps it, so the booking’s history reflects exactly what happened in the field.

What’s next

This is a preparation for upcoming booking recovery flow features. In the next weeks, based on this foundation, we will introduce structured ways to recover from a failed stop — reattempting a stop and returning undelivered goods — as first-class booking stops. We’ll announce each as it ships.

Places availability used to be indicated only under the admin section. Places launched as an admin-only feature, so the indicator lived there — but the places API has since been opened up to other roles. The new top-level flag reflects access for every role that can use places, so you can decide whether to surface places-related actions without special-casing administrators.

What’s available:

• A top-level places flag on the permissions response — a boolean in the default view, and a per-action object (index, show, create, update, destroy, fork, metadata) when requesting detailed permissions.

{ "permissions": { "places": true } }

The admin-bucket admin.places indicator is deprecated in favour of this top-level flag — see the deprecation notice.

The replacement is the new top-level places flag, which reflects access for every role that can use places — not just administrators. The detailed (per-action) shape is identical, so existing per-action checks map over directly.

Until removal, admin.places continues to work unchanged. Migrate by reading permissions.places instead of permissions.admin.places.

When the busyness signals extension is enabled, we emit a busyness.place_changed webhook for an affected place whenever its busyness shifts to a new level, from 0 (idle) to 100 (fully saturated).

Busyness signals are a paid extension configured per tenant — reach out to our customer success team to enable them.

Why this matters

Tips are set per booking, but drivers are paid per tour. Until now there was no automatic bridge between the two: tip data sat on bookings while payout reporting happened at the tour level, leaving operations to reconcile the two by hand. With automatic tip distribution, a completed tour’s compensation breakdown carries the tip total directly — visible to drivers in the app, to operators in the dashboard and API, and to your server-to-server integrations through the existing compensation webhook.

Enabling it

Tip distribution is opt-in per tour service and off by default, so nothing changes until you switch it on. Set the tour service’s tip distribution strategy with Update a service and read it back via Show a service. API support is available now; configuring it from the dashboard is coming soon.

The distribution strategy

The first available strategy, completed_dropoffs_on_tour, awards a booking’s tip to the tour where its drop-offs were completed. Bookings whose drop-offs are split across multiple tours, that still have unresolved drop-offs, or whose tip currency differs from the tour’s compensation currency don’t contribute — and a currency mismatch pauses distribution for that tour and notifies your admins by email. The default noop strategy opts out entirely. The Services docs spell out the exact eligibility rules on the strategy field — start there for the specifics.

Where the result shows up

Once a tour completes, the distributed tip appears in the tips component of its compensation breakdown — readable via Get tour compensation and delivered through tour.compensation_updated. This fills the tip slot that the tour compensation object reserved for platform-side population, and builds on booking tip currency validation, which keeps a booking’s tip currency sound before it ever reaches a tour.

This wraps up a phased retirement that already removed Fleet management from our web dashboard and mobile apps earlier this year. The capability covered vehicle inventory, operational status tracking, damage reports, and lock and unlock interactions through integrations with vehicle telematics providers such as Invers, NIU, MapTex and others. After removal, calls to the corresponding API endpoints respond with 404 Not Found.

Going forward, the MotionTools platform focuses on the booking, tour and package delivery flows that power day-to-day operations for our customers.

This brings tip currency in line with how tour-level compensation already works, and is the foundation for the upcoming automatic tip distribution onto the tour compensation object: once mismatched currencies are rejected at the source, the downstream distribution logic never has to reconcile them mid-tour.

Concretely, a booking in a EUR service area can no longer be created with a tip.currency of USD. Any caller setting a tip — whether through Create a Booking or through one of the integration ingestion endpoints — must send the same currency that already governs the booking’s pricing.

The update endpoint now reflects that workflow. Update Tour Display Configuration accepts any subset of the configuration fields, removing the need to send whole configuration on every request. Omitted fields are left untouched.

The shape of the configuration is unchanged. Show Tour Display Configuration still returns the full set of fields, and any single field that you do send is validated exactly as before. Only the request semantics have moved from “send everything” (aka PUT semantics) to “send what changed” (aka PATCH semantics).

The new object is purpose-built for the kind of compensation logic 3PL operations need: per-component editing, bonus components with self-provided keys, and a structured breakdown that is accessible to drivers. It is the foundation to build robust payroll reporting on top of, and the place to express anything richer than a flat payout number going forward.

The legacy single-amount earnings attribute it supersedes is now deprecated and will be removed on 2026-11-06.

Where to start

The full surface and its conventions live under the Tour Compensation tag — the tag overview goes deeper than this announcement on currency rules, idempotency, and how concurrency is handled. Start there if you’re integrating.

What’s new

A structured object on every tour — read the current breakdown via Get tour compensation. Three slots, all expressed in a single tour-wide currency:

• 💵 Base earnings — set with Set tour base earnings, cleared with Delete tour base earnings.
• 🎯 Bonuses — up to five named incentives, each addressable by a stable key. Set with Set tour bonus, cleared with Delete tour bonus. Bonuses come back sorted by key so the order is stable across reads.
• 💝 Tips — read-only via the API and reserved for platform-side population. Automatic tip calculation on tour completion, driven by configurable strategies, is coming soon.

total_amount is recomputed automatically whenever any component changes, and labels + metadata are kept on each component for human-readable display and audit context.

Bonus-key uniqueness as a built-in safeguard. A bonus key is enforced unique per tour. This is more than a data-model nicety: it means an accidental retry, a duplicated job, or a re-fired campaign event can’t double up the same incentive on the same tour. Use this to your benefit — pick a stable, descriptive key (completion_q1, peak_hours, late_night) for anything that should never accidentally stack, and reach for distinct keys when you genuinely want multiple incentives to coexist on the same tour.

Currency-aware writes. Every write must include currency, and the API rejects any value that doesn’t match the tour’s resolved currency (the service area’s local_currency, with fallback to the tenant-wide base_currency). This keeps tours that span service areas configured in different currencies from silently miscalculating.

Concurrency-safe writes. Per-component writes are idempotent and last-write-wins. Concurrent edits on the same component resolve via a 409 Conflict on the losing caller — read back, then retry. Writes to different components don’t contend and proceed in parallel.

A debounced webhook. Subscribe to tour.compensation_updated to react to changes. After a compensation component changes, we wait for a 120-second quiet window before firing — any further change on the same tour resets the timer. When the timer expires, a single webhook fires with the current state. Bursts of writes (e.g. setting base earnings + two bonuses in quick succession) collapse into one delivery that reflects the final state, not each intermediate step. The payload excludes labels and metadata so subscribers can act on amounts without round-tripping to our backend.

Driver-app visibility. Two new configurable labels — Compensation and Tips — surface the breakdown directly on the driver’s tour cards. The Compensation label shows the headline payout (base earnings plus bonuses, with tips excluded so the number stays stable across the tour); the Tips label surfaces the tip row separately when one is set. Both ship with sensible default prefix translations and are configurable on both the off-route and active-tour displays via Update Tour Display Configuration.

Migrating off the legacy earnings surface

The flat earnings attribute on tours, the ⚠️ Update driver earnings endpoint, and the ⚠️ tour.earnings_updated webhook are now deprecated and will be removed on 2026-11-06. The new compensation object is the migration target — see the deprecation announcement for the side-by-side guide. There’s no behavioural change to the legacy surface within the deprecation window; switch over at your own pace.

The replacement is the new Tour Compensation API: a single source of truth for what a driver is paid out for a tour, exposed as a structured, auto-totalled view across base earnings, bonuses, and tips, with a dedicated webhook for change notifications. The new surface covers everything the legacy earnings attribute did and adds the structure 3PL operations need — kept efficient on the wire by the new webhook’s quiet-window debounce, which collapses bursts of edits into a single delivery.

Until removal, the legacy endpoint, webhook, and field continue to fire unchanged. Migrate at your own pace within the deprecation window.

What’s deprecated:

• ⚠️ Update driver earnings — replaced by Set tour base earnings / Set tour bonus / Delete tour base earnings / Delete tour bonus.
• The ⚠️ tour.earnings_updated webhook — replaced by tour.compensation_updated, which carries the full structured breakdown and is debounced over a 120s quiet window so bursts of edits collapse into a single delivery reflecting the final state.
• The earnings field on tour / booking responses — read the structured breakdown via Get tour compensation instead. The compensation breakdown is intentionally not embedded in the list/detail tour responses to keep those payloads focused — fetch it on-demand from the dedicated endpoint.

What stays unchanged for the deprecation window:

• The legacy endpoint, webhook, and field continue to behave exactly as before — same payload shape, same firing conditions, same persistence. No data migration runs and no values are mirrored across the two surfaces. Pick whichever surface fits your integration today and switch over before the deadline.

Migration:

Replace single-value writes against the legacy endpoint with structured component writes against the compensation API. Each component is addressed and updated independently:

// Before — PUT /api/hailing/bookings/<tour_id>/earnings
{
  "earnings": {
    "amount": 4200,
    "currency": "EUR"
  }
}

// After — PUT /api/tours/<tour_id>/compensation/base
{
  "amount": 4000,
  "currency": "EUR",
  "label": "Base rate"
}

// After (incentive) — PUT /api/tours/<tour_id>/compensation/bonus/peak_hours
{
  "amount": 200,
  "currency": "EUR",
  "label": "Peak-hour multiplier"
}

The total_amount is recomputed automatically as components change — no need to maintain a running total client-side.

Webhook subscribers swap from a single amount/currency payload to the full structured breakdown:

// Before — tour.earnings_updated
{
  "data": {
    "tour_id": "…",
    "service_area_id": "…",
    "amount": 4200,
    "currency": "EUR"
  }
}

// After — tour.compensation_updated
{
  "data": {
    "tour_id": "…",
    "service_area_id": "…",
    "currency": "EUR",
    "total_amount": 4200,
    "breakdown": {
      "base_earnings": { "amount": 4000 },
      "bonuses": [ { "key": "peak_hours", "amount": 200 } ],
      "tips":    { "amount": 0 }
    },
    "compensation_updated_at": "2026-05-07T10:23:45Z"
  }
}

The new webhook payload excludes labels and metadata so subscribers can act on amounts without round-tripping to our backend.

This gives operators and integrators one predictable shape to build against: each reason exposes a stable machine-readable key, a localised label suitable for display, the contexts it applies to, and a properties bag carrying any category-specific flags. Clients can now render reason pickers with the same code regardless of the category, and new reason categories can be added on the server without requiring client changes to the response shape.

Stop failure reasons — returned by GET /api/reasons/stop_failure — are the predefined reasons a driver can pick from when failing a booking stop. They are sourced from a platform-maintained catalogue and localised in all supported languages.

Package failure reasons — returned by GET /api/reasons/package_failure — are the tenant-configurable reasons already used at package pickup and delivery. They are the same reasons previously served by the legacy GET /api/hailing/failure_reasons endpoint, now reshaped to fit the unified format. The legacy endpoint continues to work and is scheduled for removal — see the related deprecation announcement for the field mapping and migration details.

The unified API gives operators and integrators a single, consistent format for all configurable reasons across the platform, with localised labels and category-specific metadata kept neatly in a properties bag — so adding new categories in the future won’t require new response shapes on the client side.

Changes:

• A new GET /api/reasons/package_failure endpoint is available and returns the same tenant-configurable reasons the legacy endpoint did, in the unified reasons shape
• The legacy GET /api/hailing/failure_reasons endpoint continues to work but is deprecated
• The id → key rename and moving note_required / triggers_reattempt under a properties sub-object aligns this category with the rest of the unified reasons API

Field mapping:

Migration:

Replace calls to the legacy endpoint with the new one and adapt to the unified shape:

// Before — GET /api/hailing/failure_reasons
{
  "failure_reasons": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Recipient not at home",
      "applies_to": ["dropoff"],
      "note_required": false,
      "triggers_reattempt": true
    }
  ]
}

// After — GET /api/reasons/package_failure
{
  "reasons": [
    {
      "category": "package_failure",
      "key": "550e8400-e29b-41d4-a716-446655440000",
      "label": "Recipient not at home",
      "applies_to": {
        "stop_types": [],
        "package_interactions": ["dropoff"]
      },
      "properties": {
        "note_required": false,
        "triggers_reattempt": true
      }
    }
  ]
}

The new active_tour_labels and active_stop_labels configuration options allow you to control which labels are shown to drivers during an active tour, using the same label types available for the off-route display:

• Priority indicators
• Tour name
• Driver earnings
• Total tour distance
• Custom metadata on tours and stops
• Expected arrival time windows on stops

The scheduled_at label and the distance_to_first_stop distance variant are not available for active tours, as they are not relevant once a driver is already en-route.

Configuration is available via the existing tour display admin APIs:

Webhook events

The following webhook events now include stop_type: "return" as a possible value in their payload. If your integration inspects the stop_type field, make sure your webhook handlers accept this new value:

Service configuration

Services can now be configured with return stop settings through the admin API. When return is included in a service’s stop_types array, the following configuration fields become available:

• return_stop_duration_seconds — expected duration at the return location (default: 300 seconds)
• return_label_translations — customizable label for the return stop in multiple languages
• return_stop_default_maximum_driver_distance_meters — geofencing distance for the return location
• return_stop_default_auto_arrival_distance_meters — distance for automatic arrival marking

Creating and managing return stops

Return stops can be included when creating bookings or inserted into existing tours and bookings. The stop type on existing stops can also be changed to or from return via the update stop properties endpoint.

The public service listing also reflects whether return is enabled as a stop type:

Unlike UUIDs, service keys are immutable, descriptive identifiers (e.g., default, express) that stay stable across different tenants and between test and production environments — no need to look up the exact UUID for a specific service on each tenant. We recommend using service_key for new integrations where possible.

The service object in booking responses now includes a key field alongside the existing id, and you can discover all available service keys via the Services configuration endpoint.

Important: service_id and service_key cannot be combined in the same request. If both are provided, a validation error will be returned. When neither is given, the tenant’s default service is used — this behavior is unchanged.

New active_tour_id field

A new active_tour_id field is now available on the Users endpoint when the returned user is a driver. It’s a nullable field representing the driver’s current active tour and it’s a replacement for the active_hailing_booking_ids array field, which is now deprecated.

⚠️ Breaking Change - Failure code renames ⚠️

The following failure codes have been renamed:

• The active_driver_on_a_booking failure code returned by the Block User endpoint has been renamed to active_driver_on_a_tour.
• The on_active_booking failure code returned by Send Driver Offline endpoint has been renamed to on_active_tour.

If your integration handles these specific failure codes, please update accordingly.

The verification value is provided as an argon2id hash. The backend only validates that the value is a structurally valid argon2id hash — it never sees the plaintext. The driver app collects input from the recipient and verifies it locally against the hash.

Important: While hashing obscures the plain text, it does not keep the value secret. Values with small problem spaces — such as birth dates (~37,000 possible values in the last 100 years) or short numeric PIN codes — can still be brute-forced. Argon2id makes this computationally harder, but these values should not be considered secret.

The choice of argon2id parameters is up to the requestor. The RFC 9106 “first recommended” configuration is a good starting point.

When using the date value type, the date must be formatted as YYYY-MM-DD (ISO 8601 calendar date) before hashing with argon2id.

This new content type can be used when creating or updating stops:

Data retention: Once a booking or tour is operationally completed (reaches done, paid, or cancelled state), all verification content values are automatically anonymized. The value field is replaced with a random argon2id hash. The content item itself is preserved as a record that verification was requested.

Instruction templates with variables

Stop instructions provide a convenient way to add common tasks at stops without having to provide the full custom content schema payload. You can see available instruction templates via the dedicated endpoint:

Two new instruction templates are now available that use verification content with dynamic variables:

• birthday_verification — requires a birthdate_argon2id variable (the recipient’s date of birth, hashed with argon2id)
• pin_code_verification — requires a code_argon2id variable (a delivery PIN code, hashed with argon2id)

Instructions can now be passed as objects with a key and variables field, in addition to the existing plain string format. Existing plain-string instructions continue to work unchanged.

{
  "instructions": [
    { "key": "birthday_verification", "variables": { "birthdate_argon2id": "$argon2id$..." } }
  ]
}

Each template’s required variables and their schemas can be introspected via the variables_schema field on the list available instructions endpoint shown above.

As part of the ongoing transition from booking to tour terminology, this field has been replaced by active_tour_id, which returns the ID of the driver’s currently active tour as a single value (or null when idle).

Changes:

• A new active_tour_id field is now available on the User resource when the resource is a driver
• The existing active_hailing_booking_ids array field continues to work but is deprecated
• active_tour_id returns a single UUID or null, replacing the array which only ever contained zero or one element

Migration: Replace usage of active_hailing_booking_ids with active_tour_id:

// Before (active_hailing_booking_ids — array, always 0 or 1 elements)
{ "active_hailing_booking_ids": ["550e8400-e29b-41d4-a716-446655440000"] }

// After (active_tour_id — single value or null)
{ "active_tour_id": "550e8400-e29b-41d4-a716-446655440000" }

As part of the ongoing split between bookings and tours as distinct concepts, this filter has been replaced by on_active_tour, which provides the same functionality with naming that better reflects the underlying domain model.

Changes:

• A new on_active_tour boolean filter is now available on the List Users endpoint
• The existing on_active_hailing_booking filter continues to work but is deprecated
• Both filters behave identically — filtering drivers by whether they currently have an active tour

Migration: Replace on_active_hailing_booking with on_active_tour in your API calls:

# Before
GET /api/users?filters[on_active_hailing_booking]=true

# After
GET /api/users?filters[on_active_tour]=true

Previously, invited users were always assigned to the organization manager’s first managed organization. Now, organization managers can choose the target organization from their managed organizations list.

If no organization_id is provided, the behavior remains unchanged—the invited user defaults to the organization manager’s first managed organization.

This ensures that integrations relying on this webhook receive consistent notifications for all bookings, regardless of whether they were part of the tour from the start or were added mid-route.

This field was previously used to configure the frequency at which the next driver would be looked up for marking as preferred during gradual rollout. With the removal of the per_tour gradual rollout mode, this configuration is no longer used - the frequency is now controlled by an environment variable.

Changes:

• The field now always returns null regardless of the stored value
• Providing this field in create/update requests is still accepted but has no effect

Migration: No action is required. The field will continue to be returned in API responses (with the value null) until it is removed.

• Old response: collection_errors: { "2": [{ external_id: ["has already been taken"] }] }
• New response: collection_errors: { "2": { external_id: ["has already been taken"] } }

To keep things consistent, we’ve moved the endpoint for setting preferred drivers to be in the tours and bookings namespace, deprecating the existing endpoint that is under the hailing_bookings namespace.

Instead, you should switch to the dedicated endpoint for tours or bookings.

Before, this was a combination of preferred drivers on a tour, managing organizations and a driver from an organization having accepted a tour. This was a bit hard to see through in different operational scenarios and hence was leading to confusion, which we intend to address by having just one, simple and transparent rule for the visibility going forward.

This means that if you want to show a booking or a tour to a certain organization, you will have to set that organization as one of the managing organization.

Previously, we would base the visibility rule also off the pending driver requests, as well as off the current tour’s driver’s organization.

When creating a place, you can now pass an optional external_id string. You would normally set this to the ID of that location in your source system.

In contrast to other, location-specific attributes that require to fork a place instead of updating in place to avoid impacting historical transactional data, you can update the external_id in place (and also via Fork)

The external_id becomes indexed by our search index so you can search by it, and you can also use it as a filter on the list endpoint.

This functionality becomes particularily useful if you combine it with the newly extended corresponding external_id functionality when creating bookings.

When you create a booking, you can pass an external_id alongside each stop’s attributes. When given, we will look up the most recently created, non-archived place that belongs to the same customer and assign that to the stop.

When such a place does not yet exist, we will automatically create it instead using the address data given, and on the next booking creation it will be re-used as described above.

Please note that we do not update a previously created, matching place. If you want to update the location address data of a place, in our system that is handled as a new place via the fork mechanism, to keep historical transactional records correct.

You have three options if you want to ensure changed location data get propagated into a place:

• Change the external_id on your side based on the new location
• Remove the external_id on existing places with old location data
• Archive existing places with the same external_id

Any of these will trigger a new place to be created on the next booking creation event based on the location data given on the stop at the time. You can also omit latitude & longitude if you want to utilize our Geocoding features when you do not have GPS coordinates for your location in your system.

The same functionality is also available on the endpoints for adding individual stops into existing bookings and tours:

Together with the new booking lifecycle events, we’ve added new booking’s stop lifecycle event webhooks.

Additionally, we’ve enriched the existing booking.etas_recalculated webhook with the customer ID property, as well as the ETA info regarding the next 10 unfinished stops.

The publication of these webhooks is based off on the lifecycle of the underlying tour(s) and their stops used to complete the booking.

This can also be used with our webhook filtering feature to narrow down certain notifications to specific service areas, for example if you want to roll out an integration only gradually across certain service areas.

The updated messages are the following:

This feature allows easier integration of external systems for booking management with MotionTools, by allowing you to correlate a booking ID on the other system with booking data stored and published via MotionTools, as the booking procedes through it’s lifecycle.

This property will be returned only on bookings fetched via standard and compact views. You can also filter by the external_id on the bookings list.

The property is also included in the CSV export of the bookings.

We have also extended all our booking-related webhooks to contain the external_id when present. This allows you to more easily reference the booking on your side against your own identifier without having to store our booking ID alongside it and match them.

1. Never – Customers cannot cancel their bookings.
2. Before dispatch – Customers can cancel if none of the stops have been dispatched into a tour - this is the default.
3. Before approaching – Customers can cancel if none of the dispatched stops have reached the “approaching” status.
4. Before arrival – Customers can cancel if none of the dispatched stops have reached the “arrived” status.

This new functionality gives you more control over the booking services you offer to your customers.

You can configure the cancellation_policy via our usual service admin API endpoints:

The ability to cancel a specific booking in its current configuration and status is always indicated via the available_transitions property of our bookings payload.

Configuring this via our admin dashboard is also coming soon.

The new webhook is supposed to replace the usage of the very broad tour.modified webhook for cases when you’re interested in getting notified about tour earnings update.

This complements the corresponding feature we’ve announced back in May where this was already made possible more easily for partially_dispatched bookings.

Let’s go through some examples to outline some of the different scenarios. We’ll consider a booking with stops A and B, which are dispatched into a single tour:

Admin cancels before driver arrives at one of the stops

• The dispatched stops get removed from the tour
• The tour is empty and cancelled
• The original booking stops are cancelled
• The original booking is cancelled

Admin cancels after a driver arrived at a stop

• The arrived tour stop A will be marked as failed
• We detach the tour stop A from the booking stop A
• The tour stop B is removed from the tour
• The tour is completed and in paid status
• The original booking is cancelled

Admin cancels after a driver completed or failed a stop

Assuming the driver already completed the tour stop A and is now approaching the tour stop B

• The already completed tour stop A remains done and on the tour
• The corresponding booking stop A remains done
• The second, approaching stop B is removed from the tour and is cancelled on the booking
• The tour is completed and in paid status
• The original booking is cancelled

When the driver fails stop A the behaviour is the same except that of course the stop will now be in failed status both on the tour and booking, instead of done

Overall, the behaviour is the same as for partially_dispatched bookings or bookings that have their stops dispatched into multiple tours - but the rules will accordingly apply to all related tours and stops.

Instructions are pre-defined content that is attached to the stop, providing additional details about things to do for the driver at the stop - for example verifying the recipient’s age. You can see available instructions through the dedicated endpoint:

You can still provide your own content for the stops, alongside instructions. In such a case, the content for the instruction will be appended to the provided content.

In MotionTools when a driver goes online in the driver app as well as while they update their location while they’re online we constantly check their location against the service areas defined for the corresponding tenant.

When the driver moves between service areas we will assign them to the new area automatically. This leads to them showing up in the operations page of a service area in our dashboard as well as giving them the ability to see pickable and scheduled tours for the corresponding service areas.

We have now introduced the ability to assign drivers to one or more specific service areas. If a driver is assigned like this we won’t change their service area in the way described above anymore if the service area matching their current location is not assigned to them.

When a driver is not assigned to any specific service areas, the behaviour remains as it was before - a driver can enter any service area available on the tenant.

The corresponding API endpoints for managing assigned driver service areas that were introduced are:

The feature will soon also be available on our admin dashboard.

Upon regular booking creation we now allow customers and admins to pass an optional tip request payload. The contained fractional amount and currency code will be persisted on the booking.

We also indicate this value on the standard booking response when present.

At this time this value is simply being stored and returned, no further features are available on our platform for further usage - similar to our tour earnings mechanism, this feature simply provides a way to provide and store the data, and further processing needs to be implemented as needed via our API and other integrations.

So far, changing the requested capabilities wasn’t allowed after initial creation of a booking or tour.

Especially in the case of tours this was a bit limiting as a tour might be modified and extended during planning before being given to drivers the required capabilities for doing the tour might change - for example, a simple tour might suffice a bike vehicle, but dispatching more stops from other bookings into the same tour might make a car necessary.

Support for updating those is also soon coming to our web dashboard.

So far the booking CSV export feature was available only to the admin and organization manager roles - we have now also made this availble to customers.

Support for this has also been added to our dashboard.

Our existing managing organizations feature allows scoping the visiblity of bookings and tours to certain organizations - only drivers and organization managers on these organizations (in addition to explicitly added preferred drivers) will be able to see such bookings and tours.

This functionality is useful to scope access and operations to certain operational sub-units or subcontractors.

We have now extended this functionality with a built-in automation. You can now link certain organizations to specific service areas.

When organizations are assigned to the corresponding service area, we will now automatically set all related organizations as managing organizations when creating an empty tour or creating a tour by dispatching booking stops via these endpoints:

Consistent with our previously existing behaviour about managing organization inheritance, operations like dispatching booking stops into an existing tour do not further modify the managing organizations.

Support for managing this is also coming soon to our admin dashboard.

We want to make our platform even more adaptable to the specific needs of your business and use case, and therefore are introducing sophisticated new possibilities for configuring the way tours are shown to drivers.

In addition to already existing features like configuring the sorting order and algorithm of the pickable tours list and more, among the new configurable features you can:

• Configure how tour stops are being displayed in overview maps of lists
• Decide whether you only want to show the details of the first or first and last stop in lists

We are also introducing highly configurable labels, on both tours and stops. This allows you to choose and configure which details should be shown, and in what order, including:

• The distance to the first stop from the driver’s location
• The total tour distance
• Any metadata on the tour or any of it’s stops
• Driver Earnings
• Expected arrival time windows

You can freely add and remove these options and configure localized prefix and suffix values. For this, please use the new tour display admin APIs:

Additional driver experience related configuration options remain available via:

Support for configuring these interactively is coming soon to our admin dashboard as well, and our driver apps will receive updates in the next weeks that fully utilize these new configuration options for tour display.

Most notably, this gives you the ability to filter places based on their service area(s). Please note that service area coordinates can overlap, and hence a single place can be inside multiple service areas.

If your use case revolves around tasks at repeating customer locations, for example picking up goods at shops or meals at restaurants, it can be useful for drivers to be aware of where these locations are around them.

For this, we have introduced a new show_customer_places flag on our driver experience configuration API, which defaults to false. When enabled, drivers will be able to see the locations and names of the up to 100 non-archived customer places closest to their current location and inside their service area while online.

Support for configuring this is also available in the admin dashboard and the driver apps will soon start fetching and displaying these.

The endpoint supports the common filters also avaible on the regular package listing endpoint.

Support for creating these exports is also coming soon to our web dashboard for customers and admins.

If you’re using our booking pricing module on your tenant in certain scenarios you could have a difference in the overage distance calculated for the price and the booking distance shown in the web dashboard. The reason for this was that different sources where used for these before - now, this uses the same source for both.

Which source is being used depends on the route accuracy plan that you have purchased with us, either being straight line calculation or an actual maps-based route calculation.

Depending on your onboarding process for new drivers it can be helpful to restrict further editing of a driver’s profile details after initial onboarding. To facilitate this we have introduced a new option to restrict self-serving updates to a driver’s profile details after a successful initial onboarding.

This option is available to you upon request by reaching out to our customer success team.

Regardless of this setting admins and organization managers remain able to update a driver’s profile details using our web dashboard and the corresponding API endpoint.

When a driver is going online in the driver app we ask them about their current capabilities, which are subsequently used for selecting suitable tours.

Depending on your onboarding flow it can be necessary to do additional verifications like driver license checks during onboarding. In such situations it can be desirable to restrict the drivers ability to choose different capabilities after the initial onboarding. For this, we have extended our product with a corresponding optional configuration, allowing to restrict such updates so for example an onboarded driver always has a bike capability and cannot switch to a car without reaching out to your internal support team.

This option is available to you upon request by reaching out to our customer success team. It’s configurable whether drivers and/or org_managers can update these each, and the default remains as before that all of admins, org_managers and drivers can manage them.

Our driver apps will accordingly adapt to this setting and not offer the ability to choose corresponding capabilities that affect matching when going online.

This property has become obsolete in early 2024 with the introduction of our flexible package tours product, allowing any tour to have arbitrary stops as desired, and hasn’t been used for some time. We are now fully removing it from our API responses.

What’s new

Previously, our platform used a single, global vehicle type profile per tenant for all route calculations, regardless of the actual vehicle being used. This meant that whether your driver was using a bike, car, or truck, the system would calculate routes and estimates using the same parameters.

Now, you can configure unique vehicle type profiles for each vehicle capability value, enabling more accurate and realistic route planning that reflects the true capabilities and constraints of different vehicle types.

Why This Matters

Different vehicles have vastly different operational characteristics:

• Bikes can take shortcuts through parks and bike lanes but move slower on longer routes
• Cars balance speed and accessibility across most road types
• Trucks can require specific routes that accommodate size and weight restrictions

With vehicle-specific profiles, your route estimates and statistics will now accurately reflect these differences, leading to:

• More realistic delivery time estimates
• Improved customer expectations and satisfaction

How It Works

Configure Vehicle-Specific Profiles

You can now assign distinct vehicle type profiles to each vehicle capability value through our admin APIs:

Automatic Profile Assignment

When drivers go online in the driver app and select a vehicle capability the system automatically assigns the corresponding vehicle type profile to their account. This ensures that all subsequent tour calculations use the appropriate profile for their specific vehicle and means that estimated distances and times of arrival can change once a driver starts a tour if their vehicle type profile differs from the one requested on the tour.

Enhanced Route Calculations

The improved system now uses vehicle-specific profiles for:

• Arrival time estimates
• Tour statistics

Getting Started

If you’re already using our capability system with vehicle types, these improvements are automatically available. Simply configure vehicle type profiles for your existing vehicle capability values to start seeing more accurate route calculations.

For new implementations, the vehicle_type capability we create by default for new tenants will serve as your starting point for vehicle-specific configuration, and already comes with pre-configured vehicle_type_profile defaults.

Need help setting up vehicle type profiles for your fleet? Contact our support team or check out our API documentation for detailed implementation guidance.

Since the configuration of required proofs of delivery on tours is configured per tour service it cannot apply to off-tour package delivery & collection - therefore, a new dedicated configuration for off-tour package delivery proofs has been added to our packages configuration admin API. The available options depend on your plan at MotionTools, and specifically the purchase of the granular proofs configuration extension.

When marking a package as collected or force delivered the corresponding proofs will be collected based on this configuration in a similar way it would when delivering packages the regular way via a tour.

In addition to the API this functionality is also configurable from our booking service management in the admin dashboard.

When a package fails to be picked up or dropped of at a corresponding stop we move it into the failed status.

So far we only allowed to recover packages to one of your tenant hub places. To make resolving situations where the actual pickup of the package at its origin fails (i.e. because it wasn’t ready in time) easier we now additionally allow recovering packages to their pickup place. This makes it easier to re-attempt pickup of a package without having to do a cancel & recreate cycle.

This functionality is also available from our package management tools in the admin dashboard.

This change became necessary since depending on the configuration a forced delivery now requires additional data for proofs to be provided, which wasn’t possible with the generic transition.

This functionality was already available before in our web dashboard and via our API, but on the API it required taking a few individual calls to reach the desired state - you had to first undispatch the corresponding stops from a tour before you could move on to cancelling the booking.

With the new change the cancel transition will also appear for partially_dispatched bookings in their available_transitions via the API, and can then be cancelled using our generic booking transition endpoint.

Our package failure reason configuration already enables you to define specific failure reasons for your package pickups and deliveries in a self-serving way via the API as well as our admin dashboard.

We have now introduced an optional triggers_reattempt flag on failure reasons. When this flag is set and a package delivery is marked as failed in the driver app using a corresponding failure reason with this flag we will automatically append another delivery attempt stop at the end of the current tour. The driver can then move the stop into a reasonable position in the order using our familiar stop reordering feature in the driver app.

This new feature is intended to help in situations where upon delivery the driver becomes aware that a recipient might be able to be reached for delivery at a later point during the tour.

This can be helpful for integrating our packages with external systems as you can now more easily close the loop between passing the external_labels upon package creation and then listening for corresponding updates without having to store our own package ID or looking it up via API for identification.

This optional extension works by looking up the next closest available driver and marking them as preferred, instead of the default behaviour of pickable tours becoming immediately visible to all suitable drivers. It can help you in optimize the approach time on your tours by ensuring the closest drivers see and ideally pick tours, avoiding longer approach distances and thus driving times.

This feature is available as a paid extension via our customer success team - please reach out to us in case you are interested.

Once enabled you can configure this feature per operations configuration, so you can either have one central configuration for all of your service areas or go as detailed as having one individual per service area.

You can configure whether:

• driver_ranking is enabled
• gradual_rollout is enabled
• How long we should wait before rolling out to the next available driver via gradual_rollout_frequency_seconds

We also introduced an endpoint that allows inspecting the current ranking for drivers for a given tour:

Once the extension is enabled you can also configure it interactively through our admin dashboard.

If you offer self-pickup of packages at one of your hubs you can now facilitate this process through our packages product.

You can initiate the flow on packages that are at_hub or scheduled_for_delivery by triggering the corresponding request_collection transition:

An eligible package can then be marked as collected using the corresponding endpoint:

Our driver apps were updated accordingly, allowing to utilize this new feature from the package scanner.

This makes it easier to interpret whether a certain event listed is for example a pickup at the origin or at a hub.

• When a package is scheduled_for_delivery or out_for_delivery we will now include the latest estimated time of arrival for the package dropoff stop at the destination
• We will provide the driver’s approximate current location when they are approaching the package destination dropoff stop and the package is therefore out_for_delivery
• For packages that are out_for_delivery we will also provide the approximate number of stops for them to reach the package’s destination stop on the tour

Our public package tracking page was adjusted accordingly to reflect this additional information.

When chosen we provide the following variables for the custom algorithm:

• scheduled_in_seconds - How many seconds from now the tour is scheduled
• driver_distance_meters - How far away the viewing driver is from the first stop location
• tour_distance_meters - How long the estimated tour is in meters

Using these variables in the custom sorting algorithm can help optimize your operational efficiency significantly by increasing the likeliness drivers that pick a tour are close to the first stop, prioritize longer tours or those that are late, or any combination of these, depending on your operational requirements and optimization targets.

This feature is available as a paid extension via our customer success team - please reach out to us in case you are interested.

The configuration of the custom sorting algorithm itself can only be changed via our customer success team at this time upon your request, however once enabled you can switch it’s usage off and on using the corresponding driver experience admin API or in our web dashboard.

We are tracking arrived_at, completed_at, and failed_at timestamps on stops, as well as keeping a separate events history. So far, there could be discrepancies between the individual timestamps of these events between the events history and the dedicated timestamps - we have adjusted our stop completion logic to keep those aligned so the timestamps will always match.

We have also made adjustments to the completion of grouped stops, where we now ensure the corresponding grouped stops will also have the same timestamps throughout, matching those on the initial completed grouped stop.

Additionally our driver apps now handle clock skew in a better way - if the clock on the device of a driver is incorrect, so far the resulting stop timestamps could be wrong from the actual time the corresponding arrival or completion events occured, both in offline as well as online stop completion. We will now adjust those timestamps according to the real time based on the delta of the driver’s device clock to the actual time.

You can find the flag in permissions.removable on the package response payload, making it easier to figure out whether the operation to remove a package can be succesfully called.

We normally indicate granular permissions for specific interactions in the permissions object on responses. While the permission to remove a certain package was already indicated, it doesn’t only apply to dropoff tours, and wasn’t in the right namespace to ease API consumption, therefore we are replacing it with this new standardized property.

Before, such packages were being moved back into at_hub status the tour was originating from but this behaviour didn’t make sense in case of the force-ending of a tour as it is meant for completing the tour without the driver’s interaction.

The feature relies solely on the phone number attached to the currently active stop of a tour, which can be set either on booking or individual stop creation or by updating the stop contact details via the dedicated API endpoint or from our web dashboard.

When a driver chooses to call the stored stop phone number and the feature is enabled they will instead call a dedicated phone number specific to your tenant, and we will proxy the call to the final destination defined on the stop. The customer will see the call coming in from your tenant-wide phone number, and once connected the driver and customer are able to discuss delivery details via phone without revealing each other’s real phone numbers.

We have also included additional phone number sanitization and normalization rules which fix many common errors in the phone numbers provided by users, increasing successful phone connection percentages, and therefore speed to reach the stop, significantly.

These features are available as a paid extension via our customer success team - please reach out to us in case you are interested.

So far, you were only able to either retrieve tenant-wide places or places for specific customer IDs. We have now introduced additional options to this filter:

• customers_only - will list only customer places, but for any customer
• include_customers - will list tenant-wide places alongside customer-specific places

Additionally, when making requests as an admin we will now show some details about the customer user account for customer places in the corresponding API responses.

Our web dashboard has been adjusted accordingly to support these new options.

To facilitate this we have introduced a new driver experience API. The new API allows you to adjust the following behaviour in our driver app:

• The field to sort pickable tours by - either by scheduled_at or by the distance from the driver’s location
• The sorting direction of the pickable tours list
• The maximum number of results to show in the pickable tours list
• The maximum distance a driver can have from their current location to the first stop of a tour in the pickable list

You can use these new features to optimize the way tours are shown to drivers in a way best suitable to your business model, operations and driver availability.

A corresponding UI based configuration is also available in our admin dashboard.

In early 2024 we have changed the behaviour of our platform to make the distinction between bookings and tours clearer - bookings represent customer demand, while tours are responsible for the (optionally optimized) execution of such bookings by drivers. As a consequence of this, since then drivers cannot directly accept regular bookings anymore, with wide-ranging consequences to the events and flow a booking and a tour can have.

So far, many of our webhook events were shared between bookings and tours however, in the hailing_booking.* namespace. We are replacing these with dedicated events that more closely reflect the actual possibilities and lifecycles of their corresponding data models.

Please update all your webhook receiving endpoints and configurations accordingly to utilize the new events instead:

Booking events

Tour events

So far admins already had the ability to set an optional maximum_driver_distance_meters on stops when creating bookings, inserting custom stops into bookings or tours, or by updating them. When set a driver is prohibited to mark a stop as arrived when outside of the specified aerial distance from the stop location.

We have extended these functionalities with additional features:

Automatic arrival at stop

In addition to the maximum_driver_distance_meters we now also allow defining an auto_arrival_distance_meters on the same endpoints. When set the driver app will automatically mark the stop as arrived when the driver enters the given radius from the stop location.

Defaults from booking and tour services

Additionally to the manual passing or setting of these values via the API we now also allow defining defaults for both maximum_driver_distance_meters as well as auto_arrival_distance_meters on the booking and tour services for each stop type.

When configured stops where the corresponding service applies will automatically be created with these defaults applied.

When provided booking receipt e-mails sent by our platform will instead be delivered to this dedicated address instead of the user’s default account e-mail.

The corresponding endpoints allow for providing additional information to drivers, changing the tour name as well as attaching order images and documents. Especially the latter can be particularily helpful when additional order documentation is prepared after completion and hence can now be easily attached to the corresponding stop, booking or tour.

Historically, to update a stop’s information you had to also supply the corresponding booking ID, for example at /api/hailing/bookings/:booking_id/stops/:stop_id/metadata. Due to the ongoing split between bookings and tours you would also in the future have needed to call different endpoints depending on whether it’s a tour or booking stop.

To simplify this, we have removed the booking and tour namespacing from endpoints related to editing stop data, linked below. All of the endpoints now follow the route schema /api/stops/:id/[endpoint].

The old routes remain supported for the time being but will be removed in the future.