Servers Playground How we check Add a server Log in

OptimoRoute MCP by usefulapi

Working · 485 ms

io.usefulapi/optimoroutev1.19.0 Domain verified

Check OptimoRoute routes, orders and driver events, and create orders or start route planning.

Maps & Travel

Source Website Registry entry

Maintain this server? Claim it

Try it

Call this server's tools from your browser. Nothing to install.

https://optimoroute.usefulapi.io/mcp

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

optimoroute_create_or_update_orders Destructive

Create, update or replace up to 500 orders in one call. No geocoding here: each location must be an existing locationNo or carry latitude+longitude (+ locationNo, address or locationName). Per order, operation MERGE/SYNC/CREATE/UPDATE works as in optimoroute_create_order; by default an order matched by id or orderNo is updated with only the fields sent, otherwise created. Returns a per-order success list. OptimoRoute: POST /create_or_update_orders.

ordersarray, required

The orders, at most 500.

The server marks this tool as destructive. Running it may delete or overwrite data on the server or in any account you connected with your headers.

I understand, run it anyway

OptimoRoute MCP by usefulapi MCP server | mcptry

Tools (15)

optimoroute_create_or_update_orders

destructive

Argument	Type	Description
orders*	array	The orders, at most 500.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "orders"
  ],
  "properties": {
    "orders": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "OptimoRoute's order id. Takes priority over orderNo when matching."
          },
          "date": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "description": "Order date, YYYY-MM-DD."
          },
          "type": {
            "enum": [
              "D",
              "P",
              "T"
            ],
            "type": "string",
            "description": "D = delivery, P = pickup, T = task."
          },
          "email": {
            "type": "string",
            "description": "Customer email for notifications."
          },
          "load1": {
            "type": "number",
            "description": "Load units #1 (boxes, kg, ...) per your capacity setup."
          },
          "load2": {
            "type": "number",
            "description": "Load units #2."
          },
          "load3": {
            "type": "number",
            "description": "Load units #3."
          },
          "load4": {
            "type": "number",
            "description": "Load units #4."
          },
          "notes": {
            "type": "string",
            "description": "Notes for the driver's instructions."
          },
          "phone": {
            "type": "string",
            "description": "Customer phone number."
          },
          "skills": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Required driver skill codes."
          },
          "orderNo": {
            "type": "string",
            "description": "Your order number, shown in the web app. Used to match existing orders."
          },
          "duration": {
            "type": "number",
            "minimum": 0,
            "description": "Service time at the location, in minutes."
          },
          "location": {
            "type": "object",
            "properties": {
              "notes": {
                "type": "string",
                "description": "Notes about the location, e.g. a gate code."
              },
              "address": {
                "type": "string",
                "description": "Full address including the country, e.g. 393 Hanover St, Boston, MA 02113, USA."
              },
              "latitude": {
                "type": "number",
                "maximum": 90,
                "minimum": -90,
                "description": "Latitude."
              },
              "longitude": {
                "type": "number",
                "maximum": 180,
                "minimum": -180,
                "description": "Longitude."
              },
              "locationNo": {
                "type": "string",
                "description": "Number of an existing location. To reuse one, send ONLY locationNo (adding address or coordinates makes OptimoRoute geocode or create a new one)."
              },
              "checkInTime": {
                "type": "integer",
                "maximum": 9007199254740991,
                "minimum": 0,
                "description": "Minimum waiting time at the location, in minutes."
              },
              "locationName": {
                "type": "string",
                "description": "Location name."
              }
            },
            "description": "Where the order is serviced."
          },
          "priority": {
            "enum": [
              "L",
              "M",
              "H",
              "C"
            ],
            "type": "string",
            "description": "L low, M medium (default), H high, C critical."
          },
          "operation": {
            "enum": [
              "CREATE",
              "UPDATE",
              "MERGE",
              "SYNC"
            ],
            "type": "string",
            "description": "Per-order operation; CREATE is not allowed together with id."
          },
          "relatedId": {
            "type": [
              "string",
              "null"
            ],
            "description": "id of a related pickup/delivery."
          },
          "assignedTo": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "serial": {
                    "type": "string"
                  },
                  "externalId": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "Force the order onto one driver, e.g. {\"serial\": \"102\"} or {\"externalId\": \"444\"}. null clears it."
          },
          "timeWindows": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "twFrom",
                "twTo"
              ],
              "properties": {
                "twTo": {
                  "type": "string",
                  "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
                },
                "twFrom": {
                  "type": "string",
                  "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
                }
              }
            },
            "description": "When the order can be serviced, e.g. [{\"twFrom\": \"10:00\", \"twTo\": \"14:00\"}]."
          },
          "allowedDates": {
            "type": "object",
            "properties": {
              "to": {
                "type": "string",
                "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                "description": "Date in YYYY-MM-DD format, e.g. 2026-09-30."
              },
              "from": {
                "type": "string",
                "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                "description": "Date in YYYY-MM-DD format, e.g. 2026-09-30."
              }
            },
            "description": "Restrict the dates the order may be scheduled, e.g. {\"from\": \"2026-10-01\", \"to\": \"2026-10-07\"}."
          },
          "customField1": {
            "type": "string",
            "description": "Legacy custom field #1."
          },
          "customField2": {
            "type": "string",
            "description": "Legacy custom field #2."
          },
          "customField3": {
            "type": "string",
            "description": "Legacy custom field #3."
          },
          "customField4": {
            "type": "string",
            "description": "Legacy custom field #4."
          },
          "customField5": {
            "type": "string",
            "description": "Legacy custom field #5."
          },
          "customFields": {
            "type": "object",
            "description": "New-style custom fields keyed by the field key configured in OptimoRoute.",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": [
                "string",
                "number",
                "boolean"
              ]
            }
          },
          "relatedOrderNo": {
            "type": [
              "string",
              "null"
            ],
            "description": "orderNo of a related pickup/delivery (set on the second order of the pair)."
          },
          "allowedWeekdays": {
            "type": "array",
            "items": {
              "enum": [
                "sun",
                "mon",
                "tue",
                "wed",
                "thu",
                "fri",
                "sat"
              ],
              "type": "string"
            },
            "description": "Weekdays the order may be scheduled on. Default: all."
          },
          "vehicleFeatures": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Required vehicle feature codes."
          },
          "allowedDateTimes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "to": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Latest start, YYYY-MM-DDTHH:MM:SS."
                },
                "from": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Earliest start, YYYY-MM-DDTHH:MM:SS."
                }
              }
            },
            "description": "Datetime windows in which the service may begin."
          },
          "acceptDuplicateOrderNo": {
            "type": "boolean",
            "description": "Allow CREATE of an order whose orderNo already exists."
          },
          "notificationPreference": {
            "enum": [
              "dont_notify",
              "email",
              "sms",
              "both"
            ],
            "type": "string",
            "description": "How order-tracking notifications are delivered for this order."
          }
        }
      },
      "maxItems": 500,
      "minItems": 1,
      "description": "The orders, at most 500."
    }
  }
}

optimoroute_create_order

Create one order, or update an existing one, with address geocoding. operation: CREATE (new; errors if orderNo exists), UPDATE (existing only), MERGE (create or update only the fields you send — safest for edits), SYNC (create or REPLACE all fields with what you send). CREATE/SYNC/MERGE of a new order need date, type, location and orderNo or id. A location is either an existing locationNo alone, an address to geocode, or latitude+longitude+locationName. OptimoRoute: POST /create_order.

destructive

Argument	Type	Description
id	string	OptimoRoute's order id. Takes priority over orderNo when matching.
date	string	Order date, YYYY-MM-DD.
type	string	D = delivery, P = pickup, T = task.
email	string	Customer email for notifications.
load1	number	Load units #1 (boxes, kg, ...) per your capacity setup.
load2	number	Load units #2.
load3	number	Load units #3.
load4	number	Load units #4.

optimoroute_get_completion_details

Get the completion status of up to 500 orders (unscheduled, scheduled, on_route, servicing, success, failed, rejected, cancelled) with service start/end times and positions, proof-of-delivery form data (notes, signature and photo URLs, barcodes), the tracking URL and optionally customer feedback. Read-only despite using POST. OptimoRoute: POST /get_completion_details.

read-only

Argument	Type	Description
orders*	array	Orders to target, each {"orderNo": "..."} or {"id": "..."}. At most 500.
includeCustomerFeedback	boolean	Include the customer's rating and comment, if customer feedback is configured.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "orders"
  ],
  "properties": {
    "orders": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "OptimoRoute's unique order id."
          },
          "orderNo": {
            "type": "string",
            "description": "The user-specified order number."
          }
        }
      },
      "maxItems": 500,
      "minItems": 1,
      "description": "Orders to target, each {\"orderNo\": \"...\"} or {\"id\": \"...\"}. At most 500."
    },
    "includeCustomerFeedback": {
      "type": "boolean",
      "description": "Include the customer's rating and comment, if customer feedback is configured."
    }
  }
}

optimoroute_get_dispatch_status

Have the routes (and customer notifications) for a date been sent to drivers, when, and are they the live routes? Optionally counts routes added, modified or removed since sending. Omit date for the currently live date. OptimoRoute: GET /get_dispatch_status.

read-only

Argument	Type	Description
date	string	Date to check, YYYY-MM-DD. Omit for the live routes' date.
includeRouteChanges	boolean	Include counts of routes changed since sending.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Date to check, YYYY-MM-DD. Omit for the live routes' date."
    },
    "includeRouteChanges": {
      "type": "boolean",
      "description": "Include counts of routes changed since sending."
    }
  }
}

optimoroute_get_events

Read driver-app events for the live routes — on_duty, off_duty, start_route, end_route, start_service, success, failed, rejected, start_time_changed — up to 500 per call. Pass the returned tag as after_tag next time to get only newer events; remainingEvents says whether more are waiting. Events can arrive out of order when devices were offline. OptimoRoute: GET /get_events.

read-only

Argument	Type	Description
after_tag	string	The tag from a previous call; omit to read from the start.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "after_tag": {
      "type": "string",
      "description": "The tag from a previous call; omit to read from the start."
    }
  }
}

optimoroute_get_orders

Fetch full order data (location, time windows, assignment, loads, skills, contact) for up to 500 orders by orderNo or id. Each result has its own success flag; missing orders come back with ERR_ORD_NOT_FOUND rather than failing the call. Read-only despite using POST. OptimoRoute: POST /get_orders.

read-only

Argument	Type	Description
orders*	array	Orders to target, each {"orderNo": "..."} or {"id": "..."}. At most 500.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "orders"
  ],
  "properties": {
    "orders": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "OptimoRoute's unique order id."
          },
          "orderNo": {
            "type": "string",
            "description": "The user-specified order number."
          }
        }
      },
      "maxItems": 500,
      "minItems": 1,
      "description": "Orders to target, each {\"orderNo\": \"...\"} or {\"id\": \"...\"}. At most 500."
    }
  }
}

optimoroute_get_planning_status

Check a planning (route optimization) run started with optimoroute_start_planning: status N new, R running, C cancelled, F finished, E error, plus percentageComplete. OptimoRoute: GET /get_planning_status.

read-only

Argument	Type	Description
planningId*	integer	The planningId returned by optimoroute_start_planning.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "planningId"
  ],
  "properties": {
    "planningId": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "description": "The planningId returned by optimoroute_start_planning."
    }
  }
}

optimoroute_get_routes

Get the planned routes for one date: per driver/vehicle the duration, distance, loads and the ordered list of stops with scheduled times. Optionally filter to one driver or vehicle and include the encoded polyline, start/end locations and dispatch status. OptimoRoute: GET /get_routes.

read-only

Argument	Type	Description
date*	string	Date in YYYY-MM-DD format, e.g. 2026-09-30.
driverSerial	string	Only this driver's route (serial number).
driverExternalId	string	Only this driver's route (external id).
vehicleRegistration	string	Only this vehicle's route.
includeRoutePolyline	boolean	Include the encoded route polyline (large).
includeRouteStartEnd	boolean	Include each route's start and end locations.
includeDispatchStatus	boolean	Include whether each route was sent to its driver, and changed since.

Input schema (JSON)

optimoroute_get_scheduling_info

Is this order scheduled, and if so on which driver/vehicle, at which stop number and time, plus the live ETA from the routes sent to drivers. Give orderNo or id. OptimoRoute: GET /get_scheduling_info.

read-only

Argument	Type	Description
id	string	OptimoRoute's unique order id.
orderNo	string	The user-specified order number.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "id": {
      "type": "string",
      "description": "OptimoRoute's unique order id."
    },
    "orderNo": {
      "type": "string",
      "description": "The user-specified order number."
    }
  }
}

optimoroute_search_orders

Find orders in a date range (at most 35 days) or by a list of orderNo/id, optionally filtered by status (e.g. failed, rejected, unscheduled), with order data and/or scheduling info. Up to 500 per page; pass the returned after_tag with the SAME other parameters to get the next page. Read-only despite using POST. OptimoRoute: POST /search_orders.

read-only

Argument	Type	Description
orders	array	Orders to target, each {"orderNo": "..."} or {"id": "..."}. At most 500.
after_tag	string	Cursor from the previous page's after_tag.
dateRange	object	A date range, e.g. {"from": "2026-09-28", "to": "2026-10-02"}.
orderStatus	array	Only orders in these statuses.
includeOrderData	boolean	Include each order's full data.
includeScheduleInformation	boolean	Include each order's driver, stop number and scheduled time.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "orders": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "OptimoRoute's unique order id."
          },
          "orderNo": {
            "type": "string",
            "description": "The user-specified order number."
          }
        }
      },
      "maxItems": 500,
      "minItems": 1,
      "description": "Orders to target, each {\"orderNo\": \"...\"} or {\"id\": \"...\"}. At most 500."
    },
    "after_tag": {
      "type": "string",
      "description": "Cursor from the previous page's after_tag."
    },
    "dateRange": {
      "type": "object",
      "required": [
        "from",
        "to"
      ],
      "properties": {
        "to": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "Date in YYYY-MM-DD format, e.g. 2026-09-30."
        },
        "from": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "Date in YYYY-MM-DD format, e.g. 2026-09-30."
        }
      },
      "description": "A date range, e.g. {\"from\": \"2026-09-28\", \"to\": \"2026-10-02\"}."
    },
    "orderStatus": {
      "type": "array",
      "items": {
        "enum": [
          "unscheduled",
          "scheduled",
          "on_route",
          "servicing",
          "success",
          "failed",
          "rejected",
          "cancelled"
        ],
        "type": "string"
      },
      "description": "Only orders in these statuses."
    },
    "includeOrderData": {
      "type": "boolean",
      "description": "Include each order's full data."
    },
    "includeScheduleInformation": {
      "type": "boolean",
      "description": "Include each order's driver, stop number and scheduled time."
    }
  }
}

optimoroute_send_routes

Dispatch the routes for a date to the drivers' mobile app (the web app's Send Routes). This makes that date the live routes and CANNOT be unsent. sendNotifications defaults to FALSE here (OptimoRoute's own default is true); set it true only when you mean to email/SMS customers per the account's Order Tracking settings. Returns ERR_NOTHING_TO_SEND if nothing changed since the last send. Confirm with optimoroute_get_dispatch_status. OptimoRoute: POST /send_routes.

destructive

Argument	Type	Description
date*	string	Date in YYYY-MM-DD format, e.g. 2026-09-30.
sendNotifications	boolean	Also send customer notifications. Default false in this tool.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "date"
  ],
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Date in YYYY-MM-DD format, e.g. 2026-09-30."
    },
    "sendNotifications": {
      "type": "boolean",
      "description": "Also send customer notifications. Default false in this tool."
    }
  }
}

optimoroute_start_planning

Start OptimoRoute's route optimization for a date (or a dateRange for weekly planning, if the plan allows). With the default startWith EMPTY, existing routes for that date are REPLACED; use startWith CURRENT (+ lockType) to keep them. Returns a planningId — poll it with optimoroute_get_planning_status, then read the result with optimoroute_get_routes. Can be cancelled with optimoroute_stop_planning. OptimoRoute: POST /start_planning.

destructive

Argument	Type	Description
date	string	Date to plan, YYYY-MM-DD. Ignored if dateRange is set.
lockType	string	With CURRENT: NONE allow changes; ROUTES keep planned routes; RESOURCES keep driver per order.
balanceBy	string	Balance by WT working time or NUM order count.
balancing	string	OFF best routes; ON balance workload; ON_FORCE balance and use every driver.
dateRange	object	Plan several days at once (weekly planning).
startWith	string	EMPTY (default) plans from scratch; CURRENT starts from existing routes.
clustering	boolean	Minimize overlap between drivers' routes.

optimoroute_stop_planning

Stop a running planning (optimization) process by its planningId. OptimoRoute: POST /stop_planning.

destructive

Argument	Type	Description
planningId*	integer	The planningId returned by optimoroute_start_planning.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "planningId"
  ],
  "properties": {
    "planningId": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "description": "The planningId returned by optimoroute_start_planning."
    }
  }
}

optimoroute_update_completion_details

Set the completion status of up to 500 orders (e.g. mark success, failed or cancelled from an external system), optionally with service start/end times. Each time takes unixTimestamp, utcTime or localTime. Reversible by setting the status again. Returns a per-order success list. OptimoRoute: POST /update_completion_details.

destructive

Argument	Type	Description
updates*	array	The status updates, at most 500.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "updates"
  ],
  "properties": {
    "updates": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "OptimoRoute's unique order id."
          },
          "data": {
            "type": "object",
            "required": [
              "status"
            ],
            "properties": {
              "status": {
                "enum": [
                  "unscheduled",
                  "scheduled",
                  "on_route",
                  "servicing",
                  "success",
                  "failed",
                  "rejected",
                  "cancelled"
                ],
                "type": "string",
                "description": "The new order status."
              },
              "endTime": {
                "type": "object",
                "properties": {
                  "utcTime": {
                    "type": "string"
                  },
                  "localTime": {
                    "type": "string"
                  },
                  "unixTimestamp": {
                    "type": "integer",
                    "maximum": 9007199254740991,
                    "minimum": -9007199254740991
                  }
                },
                "description": "When service ended (success, failed)."
              },
              "startTime": {
                "type": "object",
                "properties": {
                  "utcTime": {
                    "type": "string",
                    "description": "ISO 8601, e.g. 2026-09-30T14:05:00."
                  },
                  "localTime": {
                    "type": "string",
                    "description": "ISO 8601 local time at the order location."
                  },
                  "unixTimestamp": {
                    "type": "integer",
                    "maximum": 9007199254740991,
                    "minimum": -9007199254740991
                  }
                },
                "description": "When service started (servicing, success, failed)."
              }
            }
          },
          "orderNo": {
            "type": "string",
            "description": "The user-specified order number."
          }
        }
      },
      "maxItems": 500,
      "minItems": 1,
      "description": "The status updates, at most 500."
    }
  }
}

optimoroute_update_driver_parameters

Change one driver's setup for one date: enable/disable, work hours, assigned vehicle, vehicle capacities, start/end location. WARNING: any existing route for that driver on that date is UNSCHEDULED; re-run planning afterwards. Start/end locations also apply to future optimizations. OptimoRoute: POST /update_driver_parameters.

destructive

Argument	Type	Description
date*	string	Date in YYYY-MM-DD format, e.g. 2026-09-30.
enabled	boolean	Enable or disable the driver for this date.
endAddress	string	End address shown on reports (needs end coordinates).
externalId*	string	The driver's external id from driver administration.
workTimeTo	string	Work end, 24-hour HH:MM.
endLatitude	number	End location latitude (needs endLongitude).
endLongitude	number	End location longitude (needs endLatitude).
startAddress	string

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "operation"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "OptimoRoute's order id. Takes priority over orderNo when matching."
    },
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Order date, YYYY-MM-DD."
    },
    "type": {
      "enum": [
        "D",
        "P",
        "T"
      ],
      "type": "string",
      "description": "D = delivery, P = pickup, T = task."
    },
    "email": {
      "type": "string",
      "description": "Customer email for notifications."
    },
    "load1": {
      "type": "number",
      "description": "Load units #1 (boxes, kg, ...) per your capacity setup."
    },
    "load2": {
      "type": "number",
      "description": "Load units #2."
    },
    "load3": {
      "type": "number",
      "description": "Load units #3."
    },
    "load4": {
      "type": "number",
      "description": "Load units #4."
    },
    "notes": {
      "type": "string",
      "description": "Notes for the driver's instructions."
    },
    "phone": {
      "type": "string",
      "description": "Customer phone number."
    },
    "skills": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Required driver skill codes."
    },
    "orderNo": {
      "type": "string",
      "description": "Your order number, shown in the web app. Used to match existing orders."
    },
    "duration": {
      "type": "number",
      "minimum": 0,
      "description": "Service time at the location, in minutes."
    },
    "location": {
      "type": "object",
      "properties": {
        "notes": {
          "type": "string",
          "description": "Notes about the location, e.g. a gate code."
        },
        "address": {
          "type": "string",
          "description": "Full address including the country, e.g. 393 Hanover St, Boston, MA 02113, USA."
        },
        "latitude": {
          "type": "number",
          "maximum": 90,
          "minimum": -90,
          "description": "Latitude."
        },
        "longitude": {
          "type": "number",
          "maximum": 180,
          "minimum": -180,
          "description": "Longitude."
        },
        "locationNo": {
          "type": "string",
          "description": "Number of an existing location. To reuse one, send ONLY locationNo (adding address or coordinates makes OptimoRoute geocode or create a new one)."
        },
        "checkInTime": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": 0,
          "description": "Minimum waiting time at the location, in minutes."
        },
        "locationName": {
          "type": "string",
          "description": "Location name."
        },
        "storeInvalid": {
          "type": "boolean",
          "description": "Store the order even if the address cannot be geocoded (it cannot be planned until fixed)."
        },
        "acceptPartialMatch": {
          "type": "boolean",
          "description": "Accept a lower-confidence geocoding match instead of erroring."
        },
        "acceptMultipleResults": {
          "type": "boolean",
          "description": "Accept an address that geocodes to several results instead of erroring."
        }
      },
      "description": "Where the order is serviced."
    },
    "priority": {
      "enum": [
        "L",
        "M",
        "H",
        "C"
      ],
      "type": "string",
      "description": "L low, M medium (default), H high, C critical."
    },
    "operation": {
      "enum": [
        "CREATE",
        "UPDATE",
        "MERGE",
        "SYNC"
      ],
      "type": "string",
      "description": "How to apply the order (see description)."
    },
    "relatedId": {
      "type": [
        "string",
        "null"
      ],
      "description": "id of a related pickup/delivery."
    },
    "assignedTo": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "serial": {
              "type": "string"
            },
            "externalId": {
              "type": "string"
            }
          }
        },
        {
          "type": "null"
        }
      ],
      "description": "Force the order onto one driver, e.g. {\"serial\": \"102\"} or {\"externalId\": \"444\"}. null clears it."
    },
    "timeWindows": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "twFrom",
          "twTo"
        ],
        "properties": {
          "twTo": {
            "type": "string",
            "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
          },
          "twFrom": {
            "type": "string",
            "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
          }
        }
      },
      "description": "When the order can be serviced, e.g. [{\"twFrom\": \"10:00\", \"twTo\": \"14:00\"}]."
    },
    "allowedDates": {
      "type": "object",
      "properties": {
        "to": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "Date in YYYY-MM-DD format, e.g. 2026-09-30."
        },
        "from": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "Date in YYYY-MM-DD format, e.g. 2026-09-30."
        }
      },
      "description": "Restrict the dates the order may be scheduled, e.g. {\"from\": \"2026-10-01\", \"to\": \"2026-10-07\"}."
    },
    "customField1": {
      "type": "string",
      "description": "Legacy custom field #1."
    },
    "customField2": {
      "type": "string",
      "description": "Legacy custom field #2."
    },
    "customField3": {
      "type": "string",
      "description": "Legacy custom field #3."
    },
    "customField4": {
      "type": "string",
      "description": "Legacy custom field #4."
    },
    "customField5": {
      "type": "string",
      "description": "Legacy custom field #5."
    },
    "customFields": {
      "type": "object",
      "description": "New-style custom fields keyed by the field key configured in OptimoRoute.",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": [
          "string",
          "number",
          "boolean"
        ]
      }
    },
    "relatedOrderNo": {
      "type": [
        "string",
        "null"
      ],
      "description": "orderNo of a related pickup/delivery (set on the second order of the pair)."
    },
    "allowedWeekdays": {
      "type": "array",
      "items": {
        "enum": [
          "sun",
          "mon",
          "tue",
          "wed",
          "thu",
          "fri",
          "sat"
        ],
        "type": "string"
      },
      "description": "Weekdays the order may be scheduled on. Default: all."
    },
    "vehicleFeatures": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Required vehicle feature codes."
    },
    "allowedDateTimes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "to": {
            "type": [
              "string",
              "null"
            ],
            "description": "Latest start, YYYY-MM-DDTHH:MM:SS."
          },
          "from": {
            "type": [
              "string",
              "null"
            ],
            "description": "Earliest start, YYYY-MM-DDTHH:MM:SS."
          }
        }
      },
      "description": "Datetime windows in which the service may begin."
    },
    "acceptDuplicateOrderNo": {
      "type": "boolean",
      "description": "Allow CREATE of an order whose orderNo already exists."
    },
    "notificationPreference": {
      "enum": [
        "dont_notify",
        "email",
        "sms",
        "both"
      ],
      "type": "string",
      "description": "How order-tracking notifications are delivered for this order."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "date"
  ],
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Date in YYYY-MM-DD format, e.g. 2026-09-30."
    },
    "driverSerial": {
      "type": "string",
      "description": "Only this driver's route (serial number)."
    },
    "driverExternalId": {
      "type": "string",
      "description": "Only this driver's route (external id)."
    },
    "vehicleRegistration": {
      "type": "string",
      "description": "Only this vehicle's route."
    },
    "includeRoutePolyline": {
      "type": "boolean",
      "description": "Include the encoded route polyline (large)."
    },
    "includeRouteStartEnd": {
      "type": "boolean",
      "description": "Include each route's start and end locations."
    },
    "includeDispatchStatus": {
      "type": "boolean",
      "description": "Include whether each route was sent to its driver, and changed since."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Date to plan, YYYY-MM-DD. Ignored if dateRange is set."
    },
    "lockType": {
      "enum": [
        "NONE",
        "ROUTES",
        "RESOURCES"
      ],
      "type": "string",
      "description": "With CURRENT: NONE allow changes; ROUTES keep planned routes; RESOURCES keep driver per order."
    },
    "balanceBy": {
      "enum": [
        "WT",
        "NUM"
      ],
      "type": "string",
      "description": "Balance by WT working time or NUM order count."
    },
    "balancing": {
      "enum": [
        "OFF",
        "ON",
        "ON_FORCE"
      ],
      "type": "string",
      "description": "OFF best routes; ON balance workload; ON_FORCE balance and use every driver."
    },
    "dateRange": {
      "type": "object",
      "required": [
        "from",
        "to"
      ],
      "properties": {
        "to": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "Date in YYYY-MM-DD format, e.g. 2026-09-30."
        },
        "from": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "Date in YYYY-MM-DD format, e.g. 2026-09-30."
        }
      },
      "description": "Plan several days at once (weekly planning)."
    },
    "startWith": {
      "enum": [
        "EMPTY",
        "CURRENT"
      ],
      "type": "string",
      "description": "EMPTY (default) plans from scratch; CURRENT starts from existing routes."
    },
    "clustering": {
      "type": "boolean",
      "description": "Minimize overlap between drivers' routes."
    },
    "depotTrips": {
      "type": "boolean",
      "description": "Let drivers return to the depot to reload."
    },
    "useDrivers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "driverSerial": {
            "type": "string"
          },
          "driverExternalId": {
            "type": "string"
          }
        }
      },
      "description": "Only plan with these drivers. Default: all available drivers."
    },
    "balancingFactor": {
      "type": "number",
      "maximum": 1,
      "minimum": 0,
      "description": "0.0-1.0, how much balancing outweighs route cost (ON_FORCE only)."
    },
    "useOrderObjects": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "OptimoRoute's unique order id."
          },
          "orderNo": {
            "type": "string",
            "description": "The user-specified order number."
          }
        }
      },
      "maxItems": 500,
      "minItems": 1,
      "description": "Only plan these orders. Default: all valid orders on the date."
    },
    "depotVisitDuration": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Minutes spent at a depot visit."
    },
    "midRouteDepotVisits": {
      "enum": [
        "NONE",
        "START",
        "DYNAMIC"
      ],
      "type": "string",
      "description": "Allow mid-route depot visits (needs Dynamic Mid-Route Depots on the account)."
    },
    "includeScheduledOrders": {
      "type": "boolean",
      "description": "When planning a subset, keep other orders already scheduled on those drivers (default true)."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "externalId",
    "date"
  ],
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Date in YYYY-MM-DD format, e.g. 2026-09-30."
    },
    "enabled": {
      "type": "boolean",
      "description": "Enable or disable the driver for this date."
    },
    "endAddress": {
      "type": "string",
      "description": "End address shown on reports (needs end coordinates)."
    },
    "externalId": {
      "type": "string",
      "description": "The driver's external id from driver administration."
    },
    "workTimeTo": {
      "type": "string",
      "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
      "description": "Work end, 24-hour HH:MM."
    },
    "endLatitude": {
      "type": "number",
      "description": "End location latitude (needs endLongitude)."
    },
    "endLongitude": {
      "type": "number",
      "description": "End location longitude (needs endLatitude)."
    },
    "startAddress": {
      "type": "string",
      "description": "Start address shown on reports (needs start coordinates)."
    },
    "workTimeFrom": {
      "type": "string",
      "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
      "description": "Work start, 24-hour HH:MM."
    },
    "startLatitude": {
      "type": "number",
      "description": "Start location latitude (needs startLongitude)."
    },
    "startLongitude": {
      "type": "number",
      "description": "Start location longitude (needs startLatitude)."
    },
    "assignedVehicle": {
      "type": "string",
      "description": "External id of the vehicle to assign for this date."
    },
    "vehicleCapacity1": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "description": "Vehicle load capacity #1 for this date."
    },
    "vehicleCapacity2": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "description": "Vehicle load capacity #2."
    },
    "vehicleCapacity3": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "description": "Vehicle load capacity #3."
    },
    "vehicleCapacity4": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "description": "Vehicle load capacity #4."
    }
  }
}