NagentArtefacts
Dev & Technology
Enterprise and White Glove
Company
OptimoRoute connects to a Nagent workspace with an API key. Once it is connected, agents can call 17 OptimoRoute actions, such as "Create Order", "Create or Update Orders" and "Get Order Completion Details". Nothing is enabled on connect: each action is allowed one at a time, and an action with side effects runs or waits for a person according to the agent's level.
Every operation an agent can call against OptimoRoute, with input parameters and output schema.
OPTIMOROUTE_CREATE_ORDERTool to create a new order or update an existing order in OptimoRoute. Use when you need to add delivery, pickup, or task orders to the system with location, time windows, and other constraints.
Input parameters
Unique OptimoRoute-assigned order identifier. Used for UPDATE operations
Order date in YYYY-MM-DD format
Load requirement 1
Load requirement 2
Load requirement 3
Load requirement 4
Service notes
Required driver skills
User-specified order identifier. Required unless using 'id' parameter
Service completion time in minutes
Delivery/service location information
Priority level: L (low), M (medium), H (high), or C (critical). Default: M
Specifies action - CREATE, UPDATE, SYNC, or MERGE
Order type - D (delivery), P (pickup), or T (task)
Array of time window objects
Legacy custom field value 1
Legacy custom field value 2
Legacy custom field value 3
Legacy custom field value 4
Legacy custom field value 5
Custom fields object with flexible data types
Required vehicle features
Allow duplicate orderNo if true
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
OPTIMOROUTE_CREATE_OR_UPDATE_ORDERSTool to bulk create, update, or replace multiple orders at once without geocoding. Use when you need to add new orders or modify existing ones efficiently. Supports up to 500 orders per request.
Input parameters
Array of orders to create or update. Maximum 500 orders per request.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
OPTIMOROUTE_DELETE_ALL_ORDERSTool to remove all orders and planned routes for a specified date. Use when you need to clear orders for a specific date or delete all orders system-wide if no date is provided.
Input parameters
Optional date for which to remove orders and routes in YYYY-MM-DD format. If not provided, all orders system-wide will be deleted.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
OPTIMOROUTE_DELETE_ORDERTool to remove a single order from the OptimoRoute system. Use when you need to delete a specific order by its orderNo.
Input parameters
The user-specified identifier of the order to be deleted
If true, typical restrictions on removing orders from active plans are bypassed. Defaults to false
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
OPTIMOROUTE_DELETE_ORDERSTool to delete one or more orders from the system in bulk (max 500 per request). Use when you need to remove orders, either individually or in batch operations.
Input parameters
List of orders to delete (max 500 per request). Each order must have either orderNo or id.
If true, ignores restrictions on deleting orders from live plans. Default: false.
If true, deletes all matches when multiple orders share the same identifier. Default: false.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
OPTIMOROUTE_GET_COMPLETION_DETAILSTool to retrieve completion details for one or more orders including proof of delivery data. Use when you need to check order completion status, timing details, and form data.
Input parameters
List of order identifiers to retrieve completion details for. Maximum 500 orders per request. Each order must contain either orderNo or id.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
OPTIMOROUTE_GET_DRIVERSTool to retrieve all drivers in the system. Use when you need up-to-date driver data including status and contact information.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
OPTIMOROUTE_GET_EVENTSTool to retrieve mobile events from drivers' field operations. Use when you need to track order completions, status changes (success, failed, on_duty, off_duty), and other field events for the currently active plan.
Input parameters
Marker for a prior point in time. Submit this value to retrieve only events occurring after the previous call. Leave empty for initial requests to get all events.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
OPTIMOROUTE_GET_ORDERSTool to retrieve one or more orders from OptimoRoute. Use when you need detailed order information including location, time windows, and assignment details.
Input parameters
List of order identifier objects (max 500). Each object must contain either 'orderNo' or 'id' field.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
OPTIMOROUTE_GET_PLANNING_STATUSTool to retrieve the status of an active planning/optimization process. Use when you need to check the progress of a planning job by providing its ID.
Input parameters
The ID of the planning process whose status you want to retrieve
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
OPTIMOROUTE_GET_ROUTESTool to retrieve all planned routes for a given date. Use when you need a detailed view of routes including optional stops, route parameters, and unassigned orders.
Input parameters
Date for which to retrieve routes in YYYY-MM-DD format
Filter results by driver's serial number
Filter results by driver's external identifier
Filter results by vehicle registration
Include encoded route polyline for map display
Include route's start and end locations
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
OPTIMOROUTE_GET_SCHEDULING_INFOTool to retrieve scheduling information for a specific order. Use when you need to check if an order is scheduled and get details like driver assignment, timing, and position.
Input parameters
The unique OptimoRoute-assigned order identifier. Either orderNo or id must be provided.
The user-specified order identifier. Either orderNo or id must be provided.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
OPTIMOROUTE_SEARCH_ORDERSTool to search for orders in OptimoRoute based on criteria. Use when you need to find orders by date range, order identifiers, or order status. At least one of 'orders' or 'date_range' must be provided.
Input parameters
Maximum number of orders to return per request. Use with after_tag for paginated retrieval.
List of order identifier objects to search for. Each object can contain either 'orderNo' or 'id' field.
Cursor for pagination. Pass the 'afterTag' value from a previous response to retrieve the next page of results.
Date range criteria for searching orders.
Filter by order status values (e.g., 'failed', 'rejected')
When true, includes full order data in the response. Default: false.
When true, includes scheduling information in the response. Default: false.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
OPTIMOROUTE_START_PLANNINGTool to start the planning/optimization process for a specified date or date range. Use when you need to generate optimized routes for orders and drivers. Requires orders to be created before planning can begin.
Input parameters
Target date for planning in YYYY-MM-DD format. Required if dateRange is not specified
Constrains route modifications - NONE (no constraints), ROUTES (lock routes), or RESOURCES (lock resources). Default: NONE. Only applicable when startWith is CURRENT
Balancing criteria - WT (working time) or NUM (order count). Default: WT
Route balancing mode - OFF (no balancing), ON (balanced routes), or ON_FORCE (force balancing). Default: OFF
Date range for weekly planning.
EMPTY starts fresh planning, CURRENT uses existing routes. Default: EMPTY
Deprecated - use useOrderObjects instead. List of order identifiers
Minimizes route overlap when enabled. Default: false
Enables warehouse reload scheduling. Default: false
Selected drivers to include in planning. Empty array uses all available drivers
Weighting for balanced routes, range 0.0-1.0. Default: 0.3
Orders to optimize (maximum 500 orders per request). Each object contains either orderNo or id. Empty includes all valid orders
Reload time at depot in minutes. Default: 0
Determines handling of pre-scheduled orders. Default: true
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
OPTIMOROUTE_STOP_PLANNINGTool to stop an active planning/optimization process. Use when you need to halt a running planning job by providing its ID.
Input parameters
The ID of the planning process to be stopped
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
OPTIMOROUTE_UPDATE_DRIVER_PARAMETERSTool to update driver parameters for a specific date including work times, vehicle assignment, and start/end locations. Use when you need to modify driver availability or routing constraints. Note that this unschedules existing routes for the driver on the specified date.
Input parameters
Target date in YYYY-MM-DD format
Enable or disable driver for the specified date
Ending location display address
Driver's external identifier from driver administration
End of work shift in HH:MM 24-hour format
Ending location latitude coordinate
Ending location longitude coordinate
Starting location display address
Start of work shift in HH:MM 24-hour format
Starting location latitude coordinate
Starting location longitude coordinate
Vehicle external identifier to assign
Load capacity limit for dimension 1
Load capacity limit for dimension 2
Load capacity limit for dimension 3
Load capacity limit for dimension 4
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
OPTIMOROUTE_UPDATE_DRIVERS_PARAMETERSTool to update parameters of multiple drivers for specified dates in bulk (max 500 per request). Use when you need to modify driver configuration including work hours, vehicle assignments, and location settings. Note: Existing routes for the specified drivers and dates will be unscheduled.
Input parameters
Array of driver parameter update objects (max 500)
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
Agents can call 17 OptimoRoute actions on Nagent, including "Create Order", "Create or Update Orders" and "Get Order Completion Details". Create Order: Create a new order or update an existing order in OptimoRoute. Each action is listed on this page with its input parameters and its output.
OptimoRoute connects with an API key, under your workspace's own connection. Nothing is enabled on connect: each action is allowed one at a time and can be scoped to the agents that need it.
Create Order takes 4 required inputs: date, location, operation and orderType. It also takes 19 optional inputs: id, load1, load2, load3, load4, notes, skills, orderNo, duration, priority, timeWindows, customField1, customField2, customField3, customField4, customField5, customFields, vehicleFeatures and acceptDuplicateOrderNo. It returns data, error and successful.