---
title: "Dispatch a new route"
method: POST
path: "/fleetify/routes"
tags: ["Dispatches_Routes"]
---

# Dispatch a new route

`POST /fleetify/routes`

## Query parameters

- `key` string, required

## Request body

- object
  - `driver_email` string, required — Specify the e-mail address of the driver who should receive the route. The e-mail address must be registered in [NextBillion.ai Cloud Console](https://console.nextbillion.ai/).
  - `steps` RouteStepsRequest[], required — An array of objects to collect the details about the intermediate steps in the route to be dispatched. Each object corresponds to a single step. The array must begin with a start-type step and end with an end-type step, to form a valid route. — unresolved $ref
  - `routing` RoutingRequest — The routing object allows defining the routing characteristics that should be used to generate a route when the Driver uses the in-app navigation. Only car mode is supported currently.
    - `mode` 'car' — Specify the driving mode that the service should use to determine a route
    - `approaches` 'unrestricted' | 'curb' — Specify the side of the road from which the route should approach the step location. When set to unrestricted a route can arrive at the step location from either side of the road and when set to curb the route will arrive at the step location only from the driving side of the region. Use a semi-colon ; to specify approach configurations for multiple steps.
    - `avoid` 'toll' | 'highway' | 'ferry' | 'sharp_turn' | 'uturn' | 'left_turn' | 'right_turn' | 'service_road' | 'none' — Setting this will ensure the generated route avoids the object(s) specified in the input. Multiple values should be separated by a pipe (|). If none is provided along with other values, an error is returned as a valid route is not feasible.
    - `truck_size` string — Specify the dimensions of a truck, in centimeters (cm), in the format of <height, width, length>. When specified, the dispatched route uses only those roads which allow trucks with specified dimensions. Please note this parameter is effective only when mode=truck. Also, the maximum dimensions that can be specified are as follows: Height = 1000 cm Width = 5000 cm Length = 5000 cm
    - `truck_weight` integer — Specify the weight of the truck, including trailers and shipped goods, in kilograms (kg). When specified, the dispatched route uses only those roads which allow trucks with specified weight. Please note this parameter is effective only when mode=truck. Also, the maximum weight that can be specified for a truck is 100,000 kgs.
    - `truck_axle_load` integer — Specify the total load per axle (including the weight of trailers and shipped goods) of the truck, in tonnes. When specified, the dispatched route uses only those roads which can be used by a truck to carry the specified load per axle. Please note this parameter is effective only when mode=truck.
    - `hazmat_type` 'general' | 'circumstantial' | 'explosive' | 'harmful_to_water' — Specify the type of hazardous material being carried and the dispatch service will avoid roads which are not suitable for the type of goods specified. Multiple values can be separated using a pipe operator | . Please note that this parameter is effective only when mode=truck.
  - `distance` integer — Specify the total distance, in meters, for an informative display in Driver's app. The distance specified here has no effect on the actual route that the service generates.
  - `document_template_id` string — Specify the ID of the document template that should be used to collect proof of completion for all steps in the route. In order to complete each route step, the driver will need to submit a form generated by the rules defined in the given document template. Use the [Documents API](https://docs.nextbillion.ai/docs/dispatches/documents-api) to create, read and manage document templates. Please note that the document template ID assigned to a route does not apply to following step types - start, end, break, layover.
  - `ro_request_id` string — Specify the Route Optimization request ID. When this ID is provided, all other fields will be ignored (including the required fields) and the route optimization result will be used to form the routes and corresponding steps. Please note that: * The driver's email ID must be provided in input vehicle.metadata as user_email such that the route optimization result must contain a valid driver email, step's arrival time, etc., to make a successful dispatch. * Document Template for collecting proof of delivery or completion can not be specified when using this field to dispatch a route. * In case of an error at any part among the routes, the API will immediately return the error with the index of the specific route or route step. * On a successful dispatch, the API returns the last route, if there are many, in the response payload.

## Response `200`

- object
  - `status` integer — Returns the status code of the response.
  - `data` object — An array of objects containing the details of each step in the dispatched route. Each object represents a single step.
    - `id` string — Returns the unique ID of the dispatched route.
    - `short_id` string — Returns a shorter unique ID of the dispatched route for easier referencing and displaying purposes.
    - `ro_request_id` string — Returns the route optimization request ID which was used to dispatch the route. An empty string is returned if the corresponding input was not provided.
    - `vehicle_id` string — Returns the ID of the vehicle to which the route was dispatched. The vehicle ID returned here is the same as the one used in the route optimization request for the given vehicle. An empty string is returned if the ro_request_id was not provided in the input.
    - `distance` integer — Returns the total route distance, in meters, for informative display in the driver app. It is the same as the value provided for distance field in the input request.
    - `routing` RoutingResponse — An object returning the routing characteristics that are used to generate the route and turn-by-turn navigation steps for the dispatched route. The route and navigation steps are available when driver uses the in-app navigation. Please note the routing characteristics returned here are the same as those configured in the input request. The fields which were not specified in the input will be returned as blanks.
      - `mode` string — Returns the driving mode that is used to build the route when driver starts the in-app turn-by-turn navigation.
      - `approaches` string — Returns the configuration of approaches for each step, that is used when generating the route to help the driver with turn-by-turn navigation.
      - `avoid` string — Returns the objects and maneuvers that will be avoided in the route that is built when driver starts the in-app turn-by-turn navigation.
      - `truck_weight` string — Returns the truck weight that will determine compliant routes that can be used by the driver during navigation.
      - `truck_size` string — Returns the truck dimensions, in centimeters, used to determine compliant routes that the driver can take when he starts navigating the dispatched route.
      - `truck_axle_load` string — Returns the total load per axle of the truck, in tonnes, used to determine compliant routes that the driver can take when he starts navigating the dispatched route.
      - `hazmat_type` string — Returns the hazardous cargo type that the truck is carrying. The hazardous cargo type is used to determine the compliant routes that the driver can take while navigating the dispatched route.
    - `steps` RouteStepsResponse[] — An array of objects containing the details of all steps to be performed as part of the dispatched route. Each object represents a single step during the route.
      - `id` string — Returns the unique ID of the step.
      - `short_id` string — Returns a unique short ID of the step for easier referencing and displaying purposes.
      - `type` string — Returns the step type. It can belong to one of the following: start, job , pickup, delivery, break, layover , and end. For any given step, it would be the same as that specified in the input request while configuring the step details.
      - `arrival` integer — Returns the scheduled arrival time of the driver at the step as an UNIX timestamp, in seconds precision. It is the same as that specified in the input request while configuring the step details. The timestamp returned here is only for informative display on the driver's app and it does not impact or get affected by the route generated.
      - `address` string — Returns the postal address where the step is executed. Its value is the same as that specified in the input request when configuring the step details.
      - `location` number[] — Returns the location coordinates where the step is executed.
      - `meta` object — An object returning custom details about the step that were configured in the input request while configuring the step details. The information returned here will be available for display on the Driver's app under step details.
        - `customer_phone_number` string — Returns the customer's phone number associated with the step. It can configured in the input request using the metadata attribute of the step.
        - `customer_name` string — Returns the customer name associated with the step. It can configured in the input request using the metadata attribute of the step.
        - `instructions` string — Returns the custom instructions to carry out while performing the task. These instructions can be provided at the time of configuring the step details in the input request.
      - `document_snapshot` object[] — Returns the details of the document that was used for collecting the proof of completion for the step. In case no document template ID was provided for the given step, then a null value is returned. Each object represents a new field in the document.
      - `duration` integer — Returns the duration for layover or break type steps.
      - `updated_at` integer — Represents the timestamp of the last update in seconds since the Unix epoch. Example: 1738743999.
      - `created_at` integer — Represents the timestamp of the creation in seconds since the Unix epoch. Example: 1738743999.
      - `completion` RouteStepCompletion — unresolved $ref
    - `document_snapshot` object[] — Returns the details of the document that was specified in the input for collecting the proof-of-completion for all steps in the dispatched routes. Each object represents a new field in the document.
    - `total_steps` integer — Returns the total number of steps in the dispatched route.
    - `updated_at` integer — Returns the UNIX timestamp, in seconds precision, at which this route dispatch request was updated.
    - `created_at` integer — Returns the UNIX timestamp, in seconds precision, at which this route dispatch request was created.
    - `driver` object — An object returning the details of the driver to whom the route was dispatched.
      - `id` string — Returns the ID of the driver as specified in the [NextBillion.ai](http://NextBillion.ai) Cloud Console.
      - `fullname` string — Returns the full name of the driver as specified in [NextBillion.ai](http://NextBillion.ai) Cloud Console.
      - `email` string — Returns the email of the driver as specified in the [NextBillion.ai](http://NextBillion.ai) Cloud Console.

---

[API](https://skmtc.net/nextbillion-ai/apis/one-spec-service.md) · [All operations](https://skmtc.net/nextbillion-ai/apis/one-spec-service/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nextbillion-ai/one-spec-service/revisions/b647f1808dda/schema)