Create new routes in your Routific workspace
A POST request to the /routes endpoint allows you to create an array of routes into Routific under a specific workspace. Creating routes is the first step in automating your dispatch: once routes exist for a given day, you can schedule orders onto them programmatically without a dispatcher setting them up manually each morning.
Request URL
Request Payload
[
{
"name": "Route A",
"date": "2025-07-08",
"startTime": "08:00",
"endTime": "18:00",
"capacity": 10,
"startLocation":
{
"latitude": 49.2827,
"longitude": -123.1207
},
"endLocation":
{
"latitude": 49.2827,
"longitude": -123.1207
},
"tags":
[
"refrigerated"
]
}
]
The body of the payload accepts an array of route entities, where each route entity consists of following properties.
| Fields | Type | Description |
|---|---|---|
| name (required) | String | Name of the route as it will appear in Routific. Can't be empty. |
| date (required) | Location object | The day the route runs, in YYYY-MM-DD format. |
| startTime (required) | String | When the route should start, in local time in HH:MM 24-hour format. |
| endTime (required) | String | When the route should end, in local time in HH:MM 24-hour format. |
| startLocation | Location object | Where the route begins. Latitude/Longitude is required and address is not currently supported. |
| endLocation | Location object | Where the route ends. Latitude/Longitude is required and address is not currently supported. |
| capacity | Number | The maximum capacity of the route. Uses the same unit as the "load" parameter on the Orders. |
| tags | String array | Tags can be used to restrict an order to particular route. For example, if an order has tags of ["A","B"] it can be served by a route with tags "A" or "B". If none of the routes tags match the order's tag, the order will be left unserved. Orders without a tag can be served by any route with or without a tag attached to them. |
Batch limit
A single request can create up to 50 routes. Requests exceeding this return a
400error. Routes may span multiple days within the same request based on the date attribute.
All-or-nothing
Route creation is atomic. If any route in the array fails validation, the entire request is rejected and no routes are created. Fix the offending entry and resubmit the batch request.
Sample Response Payload
[
{
"uuid": "7f2b4a19-3c8d-4e21-b9a4-1e6f5c2d8a90",
"name": "Route A",
"date": "2025-07-08",
"status": "planned",
"workspaceId": 693240,
"constraints":
{
"startTime": "08:00",
"endTime": "18:00",
"capacity": 10,
"startLocation":
{
"latitude": 49.2827,
"longitude": -123.1207
},
"endLocation":
{
"latitude": 49.2827,
"longitude": -123.1207
},
"tags":
[
"refrigerated"
]
},
"driver": null,
"ordersCount": 0,
"workingTimeInSeconds": 0,
"distanceInKilometers": 0,
"capacityUsed": 0,
"timeline":
{
"uri": "/v1/routes/7f2b4a19-3c8d-4e21-b9a4-1e6f5c2d8a90/timeline"
}
}
]
A successful request returns 201 Created with the array of created routes. Each route includes its Routific-generated uuid, which you use to reference the route in downstream requests such as scheduling orders.
| Field | Type | Description |
|---|---|---|
| uuid | String | Unique identifier of the route. |
| name | String | Name of the route. |
| date | String | Date when the route is planned for. Format: YYYY-MM-DD. |
| status | String | Current status of the route. Possible values: planned, published, executing, and completed. Newly created routes are planned. |
| workspaceId | Integer | ID of the workspace where the route belongs to. |
| constraints.startTime | String | Route start time in local time in HH:MM 24-hour format. |
| constraints.endTime | String | Route end time in local time in HH:MM 24-hour format. |
| constraints.capacity | Integer | Total capacity the route can handle. |
| constraints.startLocation | Location object | Route's start location coordinates. |
| constraints.endLocation | Location object | Route's end location coordinates. |
| constraints.tags | String array | Tag attached to the route. |
| driver | Driver object | Contains details of the driver assigned to the route like name, etc. |
| ordersCount | Integer | Number of orders assigned to the route. |
| workingTimeInSeconds | Integer | Total working time for the route in seconds. |
| distanceInKilometers | Integer | Total distance covered by the route in kilometers. |
| capacityUsed | Integer | Load assigned to the route. |
| timeline.uri | String | The URI to access additional details about a route's timeline like the sequence of stops and their associated ETAs. |