/addons/route-optimization/jobs

Submit an asynchronous route optimization job

Path

POST/api/v1/partners/addons/route-optimization/jobs

Authentication requiredapi-key

curl example

curl -X POST "https://<your-host>/api/v1/partners/addons/route-optimization/jobs" \
  -H "api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
  "external_reference": "string",
  "replaces_job_id": "string",
  "optimization_options": {
    "delivery_mode": "1",
    "kind_of_plan": "1",
    "tour_mode": "string"
  },
  "vehicles": [
    {
      "external_vehicle_id": "string",
      "resource_id": 0,
      "from_address": "string",
      "from_lat": 0,
      "from_lon": 0,
      "from_working_time": "2026-01-01T00:00:00+07:00",
      "to_working_time": "2026-01-01T00:00:00+07:00",
      "handling_unit_ids": [
        0
      ],
      "height_of_vehicle": 0,
      "length_of_vehicle": 0,
      "width_of_vehicle": 0,
      "vehicle_tonnage": 0,
      "to_address": "string",
      "to_lat": 0,
      "to_lon": 0
    }
  ],
  "orders": [
    {
      "external_order_id": "string",
      "transport_mode": "firstmile",
      "handling_unit_id": 0,
      "service_id": 0,
      "pickup_address": "string",
      "pickup_lat": 0,
      "pickup_lon": 0,
      "pickup_date_time": "2026-01-01T00:00:00+07:00",
      "pickup_date_time_to": "2026-01-01T00:00:00+07:00",
      "drop_address": "string",
      "drop_lat": 0,
      "drop_lon": 0,
      "drop_date_time": "2026-01-01T00:00:00+07:00",
      "drop_date_time_to": "2026-01-01T00:00:00+07:00",
      "rlength": 0,
      "rwidth": 0,
      "rheight": 0,
      "rweight": 0,
      "count_of_parcels": 0,
      "resource_id": 0,
      "distance": 0,
      "pickup_wid": 0,
      "drop_wid": 0,
      "loading_time": 0,
      "unloading_time": 0,
      "sender_name": "string",
      "sender_phone": "string",
      "receiver_name": "string",
      "receiver_phone": "string"
    }
  ]
}'

Parameters

Name	In	Type	Required	Description
Idempotency-Key	header	string	Yes	Client-scoped key retained indefinitely; maximum 128 chars

Request body

Completed from backend source

The specification does not describe this fully. What follows was completed by hand from the backend source code, and will be replaced once the specification carries it.

Field	Type	Required	Description
external_reference	string	No	Your own identifier for this job. 0 to 128 characters.
replaces_job_id	string (uuid)	No	Identifier of one of your own jobs still in QUEUED status. Submitting with this field atomically supersedes that job, which becomes CANCELLED: this is the only way a job reaches CANCELLED, and there is no separate cancel endpoint. The guard fires once the target job has been picked up for processing, which can happen while it still reports QUEUED; past that point the submit is refused with JOB_ALREADY_PROCESSING.
optimization_options	object	Yes	Controls how the optimizer weighs distance, vehicle count, workload balance, time windows and driver availability for this job.
vehicles	object[]	Yes	The fleet available for this job. 1 to 200 vehicles.
orders	object[]	Yes	The drop points to plan for this job. At least 1 order.

Fields of `optimization_options`

Field	Type	Required	Description
delivery_mode	'1' \| '2' \| '3' \| '4'	Yes	Delivery mode. '1' normal, '2' same day, '3' express (2 hour), '4' four hour.
kind_of_plan	'1' \| '2'	Yes	Planning mode. '1' actual planning, '2' plan in advance.
tour_mode	string	Yes	Five binary flags plus a time limit, joined by semicolons in this exact order: minimize_total_distance, minimize_vehicle_count, balance_workload, prioritize_time_windows, require_available_driver, time_limited_route. Each flag is 0 or 1; time_limited_route is an integer number of minutes, 0 meaning no limit. Example: '1;0;0;0;0;0'. Length 11 to 32 characters, pattern ^[01](;[01]){4};\d+$.

Fields of `vehicles`

Field	Type	Required	Description
external_vehicle_id	string	Yes	Your own identifier for this vehicle. 1 to 128 characters.
resource_id	integer	Yes	Internal resource identifier for the vehicle. 1 or greater.
from_address	string	Yes	Starting address of the vehicle. 1 to 500 characters.
from_lat	number	Yes	Starting point latitude. Minus 90 to 90.
from_lon	number	Yes	Starting point longitude. Minus 180 to 180.
from_working_time	string (date-time)	Yes	Start of the vehicle working window. ISO 8601 date time.
to_working_time	string (date-time)	Yes	End of the vehicle working window. ISO 8601 date time.
handling_unit_ids	integer[]	Yes	Handling unit identifiers this vehicle can carry. Maximum 100 entries.
height_of_vehicle	number	Yes	Vehicle height, in centimetres. 1 or greater. An earlier revision of this documentation named the wrong unit for this field; the stored column has always been an integer count of centimetres with no conversion applied, so submit the value directly in centimetres.
length_of_vehicle	number	Yes	Vehicle length, in centimetres. 1 or greater. See the note on height_of_vehicle above.
width_of_vehicle	number	Yes	Vehicle width, in centimetres. 1 or greater. See the note on height_of_vehicle above.
vehicle_tonnage	number	Yes	Vehicle payload capacity, in kilograms despite the field name. 0 or greater. The stored column is an integer count of kilograms with no conversion applied, so submit the value directly in kilograms.
to_address	string	No	Ending address of the vehicle, if different from the start. 0 to 500 characters.
to_lat	number	No	Ending point latitude, if the vehicle ends somewhere other than from_lat.
to_lon	number	No	Ending point longitude, if the vehicle ends somewhere other than from_lon.

Fields of `orders`

Field	Type	Required	Description
external_order_id	string	Yes	Your own identifier for this order. 1 to 128 characters.
transport_mode	'firstmile' \| 'midmile' \| 'lastmile'	Yes	Which leg of the haul this order belongs to.
handling_unit_id	integer	Yes	Handling unit identifier for the cargo. 1 or greater.
service_id	integer	Yes	Service identifier for the order. 1 or greater.
pickup_address	string	Yes	Pickup address. 1 to 500 characters.
pickup_lat	number	Yes	Pickup point latitude.
pickup_lon	number	Yes	Pickup point longitude.
pickup_date_time	string (date-time)	Yes	Start of the pickup window. ISO 8601 date time.
pickup_date_time_to	string (date-time)	Yes	End of the pickup window. ISO 8601 date time.
drop_address	string	Yes	Drop off address. 1 to 500 characters.
drop_lat	number	Yes	Drop off point latitude.
drop_lon	number	Yes	Drop off point longitude.
drop_date_time	string (date-time)	Yes	Start of the drop off window. ISO 8601 date time.
drop_date_time_to	string (date-time)	Yes	End of the drop off window. ISO 8601 date time.
rlength	number	Yes	Cargo length, in centimetres. 0 or greater.
rwidth	number	Yes	Cargo width, in centimetres. 0 or greater.
rheight	number	Yes	Cargo height, in centimetres. 0 or greater.
rweight	number	Yes	Cargo weight, in kilograms. 0.01 or greater.
count_of_parcels	integer	Yes	Number of parcels in this order. 1 or greater.
resource_id	integer	No	Internal resource identifier, if known. 0 or greater.
distance	number	No	Known distance for this order, in kilometres, if you have one. 0 or greater.
pickup_wid	integer	No	Pickup warehouse identifier. 0 or greater.
drop_wid	integer	No	Drop off warehouse identifier. 0 or greater.
loading_time	integer	No	Loading time, in minutes. 0 or greater.
unloading_time	integer	No	Unloading time, in minutes. 0 or greater.
sender_name	string	No	Sender name. 0 to 200 characters.
sender_phone	string	No	Sender phone number. 0 to 32 characters.
receiver_name	string	No	Receiver name. 0 to 200 characters.
receiver_phone	string	No	Receiver phone number. 0 to 32 characters.

5 fieldsCreateRouteOptimizationJobDto

Responses

202Public job aggregate committed

400ROUTE_OPT_VALIDATION_ERROR or DUPLICATE_EXTERNAL_ID

409IDEMPOTENCY_CONFLICT, ACTIVE_EXTERNAL_ID_CONFLICT, or JOB_ALREADY_PROCESSING

413ROUTE_OPT_PAYLOAD_TOO_LARGE

429ROUTE_OPT_RATE_LIMITED

Back to group: Route optimisation