Route Dispatch API

Introduction

The Route Dispatch API allows sharing of complex routes, including tasks, locations, breaks, and layovers, to NextBillion.ai drivers. Routes can be linked to customizable forms for recording proof-of-completion and can include turn-by-turn navigation instructions to assist drivers.

Let’s take a look at the various methods available within Route Dispatch API below.

Dispatch a new route

Dispatching a route to registered drivers is possible by submitting their registered email addresses in the input request. All valid routes must contain a start and an end step. The request can also include route data (stops, task type, instructions, routing characteristics) and a pre-created document template’s ID to record proof-of-completion at all route steps. If needed, the linked template can be overridden at a step level by providing a different template ID for the given step.

To dispatch the routes to your drivers, register them at NextBillion.ai Cloud Console

To create and manage document templates, check out our Documents API

Once a route is successfully configured using the following endpoint, the driver can get all the details of the route on the Driver app, available on Android & iOS.

POST

https://api.nextbillion.io/fleetify/routes?key={your_api_key}

Let’s take a look at the available parameters.

Request Parameters

Request Body

Response Schema

Sample Request

1
curl --location 'https://api.nextbillion.io/fleetify/routes?key=<your_api_key> \
2
--header 'Content-Type: application/json' \
3
--data-raw '{
4
  "driver_email": "[email protected]",
5
  "distance": 8775,
6
  "routing": {
7
    "mode": "car"
8
  },
9
  "steps": [
10
    {
11
      "type": "start",
12
      "arrival": 1740740400,
13
      "location": [34.0928, -118.2829]
14
    },
15
    {
16
      "type": "job",
17
      "arrival": 1740740400,
18
      "location": [34.0928, -118.2829],
19
      "address": "1234 Sunset Boulevard, Los Angeles, CA 90026",
20
      "metadata": {
21
        "customer_name": "Matthew",
22
        "customer_phone_number": "779-408-9942",
23
        "instructions": "Knock on the door and pet the dog"
24
      }
25
    },
26
    {
27
      "type": "job",
28
      "arrival": 1740741300,
29
      "location": [34.1015, -118.3269],
30
      "address": "5678 Hollywood Boulevard, Los Angeles, CA 90028",
31
      "metadata": {
32
        "customer_name": "David",
33
        "customer_phone_number": "453-567-1000",
34
        "instructions": "Call the customer before arrival"
35
      }
36
    },
37
    {
38
      "type": "end",
39
      "arrival": 1740741300,
40
      "location": [34.1015, -118.3269]
41
    }
42
  ],
43
  "document_template_id": "24c1615a-a031-43e7-ae97-834fdd600614"
44
}'

Sample Response

1
{
2
   "status": 201,
3
   "data": {
4
       "id": "be39c08c-1ca2-4a78-9d17-db4f17bec6ae",
5
       "short_id": "tqmn-597596",
6
       "ro_request_id": "",
7
       "vehicle_id": "",
8
       "distance": 8775,
9
       "routing": {
10
           "mode": "car"
11
       },
12
       "steps": [
13
           {
14
               "id": "722686a2-c2cd-4c41-93a9-79f87be79b0b",
15
               "short_id": "esyu-359768",
16
               "type": "start",
17
               "arrival": 1740740400,
18
               "address": "",
19
               "location": [
20
                   34.0928,
21
                   -118.2829
22
               ],
23
               "meta": {
24
                   "customer_phone_number": "",
25
                   "customer_name": "",
26
                   "instructions": ""
27
               },
28
               "updated_at": 1740313332,
29
               "created_at": 1740313332
30
           },
31
           {
32
               "id": "ae258f5c-b978-4c77-912f-b3b915a1ce96",
33
               "short_id": "keud-934809",
34
               "type": "job",
35
               "arrival": 1740740400,
36
               "address": "1234 Sunset Boulevard, Los Angeles, CA 90026",
37
               "location": [
38
                   34.0928,
39
                   -118.2829
40
               ],
41
               "meta": {
42
                   "customer_phone_number": "779-408-9942",
43
                   "customer_name": "Matthew",
44
                   "instructions": "Knock on the door and pet the dog"
45
               },
46
               "updated_at": 1740313332,
47
               "created_at": 1740313332
48
           },
49
           {
50
               "id": "35f40ee2-1e08-4089-809d-630e3f20d09c",
51
               "short_id": "bzyv-845051",
52
               "type": "job",
53
               "arrival": 1740741300,
54
               "address": "5678 Hollywood Boulevard, Los Angeles, CA 90028",
55
               "location": [
56
                   34.1015,
57
                   -118.3269
58
               ],
59
               "meta": {
60
                   "customer_phone_number": "453-567-1000",
61
                   "customer_name": "David",
62
                   "instructions": "Call the customer before arrival"
63
               },
64
               "updated_at": 1740313332,
65
               "created_at": 1740313332
66
           },
67
           {
68
               "id": "2c09cc64-e3ba-4d3d-aedf-492547ae61da",
69
               "short_id": "riiu-491234",
70
               "type": "end",
71
               "arrival": 1740741300,
72
               "address": "",
73
               "location": [
74
                   34.1015,
75
                   -118.3269
76
               ],
77
               "meta": {
78
                   "customer_phone_number": "",
79
                   "customer_name": "",
80
                   "instructions": ""
81
               },
82
               "updated_at": 1740313332,
83
               "created_at": 1740313332
84
           }
85
       ],
86
       "document_snapshot": [
87
           {
88
               "type": "multi_choices",
89
               "label": "Package Type",
90
               "required": true,
91
               "meta": {
92
                   "options": [
93
                       {
94
                           "label": "Food",
95
                           "value": "Food"
96
                       },
97
                       {
98
                           "label": "Electronics",
99
                           "value": "Electronics"
100
                       },
101
                       {
102
                           "label": "Medicines",
103
                           "value": "Medicines"
104
                       }
105
                   ]
106
               }
107
           },
108
           {
109
               "label": "Photos",
110
               "validation": {
111
                   "max_items": 3,
112
                   "min_items": 1
113
               },
114
               "name": "photos",
115
               "type": "photos",
116
               "required": true
117
           }
118
       ],
119
       "total_steps": 4,
120
       "updated_at": 1740313332,
121
       "created_at": 1740313332,
122
       "driver": {
123
           "id": "271107797150630408",
124
           "fullname": "John Doe",
125
           "email": "[email protected]"
126
       }
127
   }
128
}
129

130

Modify a dispatched route

Once a route has been dispatched, its steps can be modified by sending a request to the following method:

POST

https://api.nextbillion.io/fleetify/v2/routes/{route_id}/redispatch?key={your_api_key}

The operation parameter allows adding new steps, updating and deleting steps from an already dispatched route. The steps can be modified as long as they have not been completed or started. Once a request is submitted successfully, the service responds with complete details of the modified route.

Let’s take a look at the available parameters under this method.

Request Parameters

Request Body

Response Schema

Sample Request

1
curl --location 'https://api.nextbillion.io/fleetify/v2/routes/tqmn-597596/redispatch?key=<opensesame>' \
2
--header 'Content-Type: application/json' \
3
--data '{
4
    "distance": 7834,
5
    "operations": [
6
        {
7
            "operation": "create",
8
            "data": {
9
                "step": {
10
                    "type": "delivery",
11
                    "arrival": 1740740700,
12
                    "location": [
13
                       34.09511876925524, -118.32605708487887
14
                    ],
15
                    "address": "1234 Sunset Blvd, Los Angeles, CA 90026",
16
                    "metadata": {
17
                        "customer_name": "Costco",
18
                        "customer_phone_number": "654-542-0392",
19
                        "instructions": "Drop the box at the back door"
20
                    }
21
                }
22
            }
23
        },
24
        {
25
            "operation": "update",
26
            "data": {
27
                "step_id": "keud-934809",
28
                "step": {
29
                    "type": "job",
30
                    "arrival": 1740741000,
31
                    "location": [
32
                        34.042256346743166, -118.33157494526539
33
                    ],
34
                    "address": "5678 Hollywood Ave, Los Angeles, CA 90028",
35
                    "metadata": {
36
                        "customer_name": "Ray Rogers",
37
                        "customer_phone_number": "111-093-5432",
38
                        "instructions": "knock on the door twice and pet the dog"
39
                    }
40
                }
41
            }
42
        },
43
        {
44
            "operation": "delete",
45
            "data": {
46
                "step_id": "bzyv-845051",
47
                "step": {
48
                    "type": "delivery",
49
                    "arrival": 1773208800,
50
                    "location": [
51
                       34.066903083673715, -118.27135829496032
52
                    ],
53
                    "address": "91011 Beverly Ln, Los Angeles, CA 90210"
54
                }
55
            }
56
        }
57
    ]
58
}'

Sample Response

1
{
2
    "status": 200,
3
    "data": {
4
        "id": "be39c08c-1ca2-4a78-9d17-db4f17bec6ae",
5
        "short_id": "tqmn-597596",
6
        "ro_request_id": "",
7
        "vehicle_id": "",
8
        "distance": 7834,
9
        "routing": {
10
            "mode": "car"
11
        },
12
        "steps": [
13
            {
14
                "id": "722686a2-c2cd-4c41-93a9-79f87be79b0b",
15
                "short_id": "esyu-359768",
16
                "type": "start",
17
                "arrival": 1740740400,
18
                "address": "",
19
                "location": [
20
                    34.0928,
21
                    -118.2829
22
                ],
23
                "meta": {
24
                    "customer_phone_number": "",
25
                    "customer_name": "",
26
                    "instructions": ""
27
                },
28
                "completion": {
29
                    "status": "scheduled"
30
                },
31
                "updated_at": 1740313332,
32
                "created_at": 1740313332
33
            },
34
            {
35
                "id": "9bb8260e-1ccb-4252-8cd4-e1493efa16d4",
36
                "short_id": "tfij-737449",
37
                "type": "delivery",
38
                "arrival": 1740740700,
39
                "address": "1234 Sunset Blvd, Los Angeles, CA 90026",
40
                "location": [
41
                    34.09511876925524,
42
                    -118.32605708487887
43
                ],
44
                "meta": {
45
                    "customer_phone_number": "654-542-0392",
46
                    "customer_name": "Costco",
47
                    "instructions": "Drop the box at the back door"
48
                },
49
                "completion": {
50
                    "status": "scheduled"
51
                },
52
                "updated_at": 1740313870,
53
                "created_at": 1740313870
54
            },
55
            {
56
                "id": "ae258f5c-b978-4c77-912f-b3b915a1ce96",
57
                "short_id": "keud-934809",
58
                "type": "job",
59
                "arrival": 1740741000,
60
                "address": "5678 Hollywood Ave, Los Angeles, CA 90028",
61
                "location": [
62
                    34.0422563467432,
63
                    -118.331574945265
64
                ],
65
                "meta": {
66
                    "customer_phone_number": "111-093-5432",
67
                    "customer_name": "Ray Rogers",
68
                    "instructions": "knock on the door twice and pet the dog"
69
                },
70
                "completion": {
71
                    "status": "scheduled"
72
                },
73
                "updated_at": 1740313870,
74
                "created_at": 1740313332
75
            },
76
            {
77
                "id": "2c09cc64-e3ba-4d3d-aedf-492547ae61da",
78
                "short_id": "riiu-491234",
79
                "type": "end",
80
                "arrival": 1740741300,
81
                "address": "",
82
                "location": [
83
                    34.1015,
84
                    -118.3269
85
                ],
86
                "meta": {
87
                    "customer_phone_number": "",
88
                    "customer_name": "",
89
                    "instructions": ""
90
                },
91
                "completion": {
92
                    "status": "scheduled"
93
                },
94
                "updated_at": 1740313332,
95
                "created_at": 1740313332
96
            }
97
        ],
98
        "document_snapshot": [
99
            {
100
                "type": "multi_choices",
101
                "label": "Package Type",
102
                "required": true,
103
                "meta": {
104
                    "options": [
105
                        {
106
                            "label": "Food",
107
                            "value": "Food"
108
                        },
109
                        {
110
                            "label": "Electronics",
111
                            "value": "Electronics"
112
                        },
113
                        {
114
                            "label": "Medicines",
115
                            "value": "Medicines"
116
                        }
117
                    ]
118
                }
119
            },
120
            {
121
                "label": "Photos",
122
                "validation": {
123
                    "max_items": 3,
124
                    "min_items": 1
125
                },
126
                "name": "photos",
127
                "type": "photos",
128
                "required": true
129
            }
130
        ],
131
        "completion": {
132
            "status": "scheduled"
133
        },
134
        "total_steps": 4,
135
        "completed_steps": 0,
136
        "updated_at": 1740313870,
137
        "created_at": 1740313332,
138
        "driver": {
139
            "id": "271107797150630408",
140
            "fullname": "John Doe",
141
            "email": "[email protected]"
142
        }
143
    }
144
}

API Query Limits

The maximum number of steps that can be provided in the input are 1000.
arrival should always be either equal to or greater than the current time and it should increase monotonically for each step.
NextBillion.ai allows a maximum rate limit of 6000 queries per minute or 100 queries/second for continuous requests.
1. Note: We can increase the quota if needed on request. Contact [email protected] for more details.

API Error Codes

Response code	Description	Additional notes
200	Normal success case.	Normal success case.
400	Input validation failed.	There is a missing or an invalid parameter or a parameter with an invalid value type is added to the request.
401	APIKEY not supplied or invalid	This error occurs when the wrong API key is passed in the request or the key is missing altogether.
403	APIKEY is valid but does not have access to requested resources	You might be querying for a geographical region which is not valid for your account or requesting a service which is not enabled for you.
404	Requested host/path not found	This error occurs when a malformed hostname is used.
422	Could not process the request	A feasible solution could not be generated for the given set of locations or parameter configuration.
429	Too many requests	QPM reached or API request count quota reached.
500	Internal Service error.	There was an internal issue with NextBillion.ai services. You can reach out to [email protected] for an explanation.