One-off scheduling

POST https://api.plan.routific.com/v2/schedules

Optimize a self-contained problem without a workspace

A POST request to the /schedules endpoint without a workspaceUuidruns a one-off optimization. You send the complete problem — routes, orders, and preferences — in a single request, and Routific returns an optimized plan. Nothing needs to exist in your account beforehand.

Use this when you want Routific's optimization engine as a standalone solver: comparing fleet configurations for the same day, sizing a prospective route network, or running a what-if plan without touching your live operation.

Request URL

post https://api.plan.routific.com/v2/schedules

📘

The absence of a workspace selects this mode

The same endpoint serves both scheduling surfaces. Supplying workspaceUuid schedules against existing workspace data — see Schedule Orders. Omitting it, and sending routesData and ordersData instead, runs a one-off job.

Request Payload

JSON

{
    "routesData":
    [
        {
            "name": "Van 1",
            "constraints":
            {
                "startTime": "09:00",
                "endTime": "17:00",
                "capacity": 100,
                "startLocations":
                [
                    {
                        "address": "455 Granville St, Vancouver",
                        "latitude": 49.2846,
                        "longitude": -123.1122
                    }
                ],
                "endLocations":
                [
                    {
                        "latitude": 49.2846,
                        "longitude": -123.1122
                    }
                ],
                "tags": ["fridge"]
            }
        }
    ],
    "ordersData":
    [
        {
            "name": "Order #1042",
            "locations":
            [
                {
                    "address": "800 Robson St, Vancouver",
                    "latitude": 49.2827,
                    "longitude": -123.1207
                }
            ],
            "duration": 10,
            "load": 4,
            "timeWindows":
            [
                {
                    "startTime": "12:00",
                    "endTime": "16:00"
                }
            ],
            "tags": ["fridge"],
            "displayOrderId": "1042",
            "customerOrderNumber": "SO-2231"
        }
    ],
    "options":
    {
        "minimizeRoutes": true
    }
}

🚧

There is no date on a one-off request

A one-off problem is dateless. Shift times and time windows are clock times in HH:mm that Routific anchors internally. Sending a date field will be rejected.

Fields	Type	Description
ordersData	Array	The vehicles available for this problem. Maximum 500.
routesData	Array	The stops to be scheduled. Maximum 5,000.
options	Object	Optimization preferences. See below for more information.

🚧

Use routesData and ordersData, not routes and orders

The plain routes and orders fields reference entities that already exist in a workspace, and are rejected here — there is nothing to reference on this surface. Mixing the two forms in one request is also rejected.

ordersData object

Each entry describes one order to be scheduled. These are the same fields accepted by Create orders.

routesData object

Each entry describes one route available for the optimization. These are the same fields accepted by Create routes

Options object

Your workspace's optimization preferences are used by default — the same preferences the Routific app uses. The options object overrides them temporarily for this request, and is not saved back to the workspace.

Fields	Type	Description
minimizeRoutes	Boolean	Preference to find solution with fewest vehicles rather than the shortest total working time.
balanceType	String	Preference for how to balance workload across all routes. Currently accepts none, or orders for no balance prefernce or to balance by number of order across routes, respectively.
flexibleStartTime	Boolean	Allow a route to start later than its start time when doing so reduces idle time across the route that may be the result of time-window constraints.
excludeTolls	Boolean	Avoid toll roads when routing.
excludeFerry	Boolean	Avoid ferry routes when routing.
squashDuration	Number	Reduces service duration to the specified value for each consecutive order at the same location.
defaultOrderDuration	Number	Service duration applied to orders that have no duration of their own.
allowCapacityOverload	Boolean	Allow routes to exceed their capacity rather than leaving orders unscheduled.
allowRouteOvertime	Boolean	Allow routes to run past their end time rather than leaving orders unscheduled.
allowVisitLateness	Boolean	Allow arrival after an order's time window rather than leaving the order unscheduled.

📘

Scheduling is asynchronous

The POST returns 202 Accepted with an actionUuid — it does not return the plan. Poll GET /v2/schedules/{actionUuid} until status is finished or failed.

Response Payload

JSON

{
    "actionUuid": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
    "actionName": "schedule",
    "status": "pending"
}

Fields	Type	Description
actionUuid	String	Identifies this scheduling run request. Use it to poll for status and to fetch the solution.
actionName	String	The type of action performed. Always schedule for this endpoint.
status	String	The status of the run. Always pending on creation. Possible values: pending, finished, failed.