Documents API

Introduction

NextBillion.ai’s Documents API allows users to create form templates for collecting required information. Users can add fields and configure their names, data types and even validation rules to maintain data integrity and quality standards. Once created, these forms can be used for collecting information like - proof of completion or proof of delivery - while executing planned routes.

Users can link a document to a specific route via the Dispatch API. Once linked successfully, the Driver would be required to record the information in the document for each task step on the dispatched route. The drivers can access the documents for each task step via their Driver app, available on Android & iOS, once the associated route is dispatched successfully.

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

Let’s take a look at the methods available to manage documents.

Create a Document Template

This endpoint allows users to create a document template. Users need to configure a unique name for the template. Once the request is successfully submitted, the service responds with an unique identifier for the document which can be used to reference this template when dispatching routes.

POST

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

Request Parameters

Request Body

Response Schema

Sample Request

1
curl --location 'https://api.nextbillion.io/fleetify/document_templates?key=<your_api_key>' \
2
--header 'Content-Type: application/json' \
3
--data '{
4
  "name": "sample_template",
5
  "content": [
6
    {
7
      "type": "multi_choices",
8
      "label": "Package Type",
9
      "required": true,
10
      "meta": {
11
        "options": [
12
          {
13
            "label": "Food",
14
            "value": "Food"
15
          },
16
          {
17
            "label": "Electronics",
18
            "value": "Electronics"
19
          },
20
          {
21
            "label": "Medicines",
22
            "value": "Medicines"
23
          }
24
        ]
25
      }
26
    },
27
    {
28
      "label": "Photos",
29
      "validation": {
30
        "max_items": 3,
31
        "min_items": 1
32
      },
33
      "name": "photos",
34
      "type": "photos",
35
      "required": true
36
       }
37
  ]
38
}'

Sample Response

1
{
2
   "status": 200,
3
   "data": {
4
       "id": "86eb43f2-c961-40a3-92c6-b039a3eb821b",
5
       "content": [
6
           {
7
               "type": "multi_choices",
8
               "label": "Package Type",
9
               "required": true,
10
               "meta": {
11
                   "options": [
12
                       {
13
                           "label": "Food",
14
                           "value": "Food"
15
                       },
16
                       {
17
                           "label": "Electronics",
18
                           "value": "Electronics"
19
                       },
20
                       {
21
                           "label": "Medicines",
22
                           "value": "Medicines"
23
                       }
24
                   ]
25
               }
26
           },
27
           {
28
               "label": "Photos",
29
               "validation": {
30
                   "max_items": 3,
31
                   "min_items": 1
32
               },
33
               "name": "photos",
34
               "type": "photos",
35
               "required": true
36
           }
37
       ],
38
       "name": "sample_template"
39
   }
40
}

Retrieve a Document Template

This endpoint allows users to retrieve a document template using its unique ID.

GET

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

Request Parameters

Response Schema

Sample Request

1
curl --location 'https://api.nextbillion.io/fleetify/document_templates/86eb43f2-c961-40a3-92c6-b039a3eb821b?key=<your_api_key>'

Sample Response

1
{
2
    "status": 200,
3
    "data": {
4
        "id": "86eb43f2-c961-40a3-92c6-b039a3eb821b",
5
        "content": [
6
            {
7
                "type": "multi_choices",
8
                "label": "Package Type",
9
                "required": true,
10
                "meta": {
11
                    "options": [
12
                        {
13
                            "label": "Food",
14
                            "value": "Food"
15
                        },
16
                        {
17
                            "label": "Electronics",
18
                            "value": "Electronics"
19
                        },
20
                        {
21
                            "label": "Medicines",
22
                            "value": "Medicines"
23
                        }
24
                    ]
25
                }
26
            },
27
            {
28
                "label": "Photos",
29
                "validation": {
30
                    "max_items": 3,
31
                    "min_items": 1
32
                },
33
                "name": "photos",
34
                "type": "photos",
35
                "required": true
36
            }
37
        ],
38
        "name": "sample_template"
39
    }
40
}

Update a Document Template

This endpoint allows users to update a specific document template using its unique ID. Please note that updating the content attribute of a template overwrites all the existing items for the given template.

PUT

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

Request Parameters

Request Body

Response Schema

Sample Request

1
curl --location --request PUT 'https://api.nextbillion.io/fleetify/document_templates/886abfe6-0068-48aa-988a-8639dad228c5?key=<your_api_key>' \
2
--header 'Content-Type: application/json' \
3
--data '{
4
    "name":"Sample_template_1",
5
    "content": [
6
                {
7
                    "type": "string",
8
                    "name": "OTP verification",
9
                    "label": "OTP",
10
                    "required": true
11
                },
12
                {
13
                    "type": "date_time",
14
                    "name": "Completion Time",
15
                    "label": "Completed at:",
16
                    "required": true
17
                }
18
            ]
19
}'

Sample Response

1
{
2
    "status": 200,
3
    "data": {
4
        "id": "886abfe6-0068-48aa-988a-8639dad228c5",
5
        "content": [
6
            {
7
                "type": "string",
8
                "name": "OTP verification",
9
                "label": "OTP",
10
                "required": true
11
            },
12
            {
13
                "type": "date_time",
14
                "name": "Completion Time",
15
                "label": "Completed at:",
16
                "required": true
17
            }
18
        ],
19
        "name": "Sample_template_1"
20
    }
21
}

Retrieve all Document Templates

This endpoint allows users to retrieve all document templates associated with an API key.

GET

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

Request Parameters

Response Schema

Sample Request

1
curl --location 'https://api.nextbillion.io/fleetify/document_templates?key=<your_api_key>'

Sample Response

1
{
2
    "status": 200,
3
    "data": [
4
        {
5
            "id": "86eb43f2-c961-40a3-92c6-b039a3eb821b",
6
            "content": [
7
                {
8
                    "type": "multi_choices",
9
                    "label": "Package Type",
10
                    "required": true,
11
                    "meta": {
12
                        "options": [
13
                            {
14
                                "label": "Food",
15
                                "value": "Food"
16
                            },
17
                            {
18
                                "label": "Electronics",
19
                                "value": "Electronics"
20
                            },
21
                            {
22
                                "label": "Medicines",
23
                                "value": "Medicines"
24
                            }
25
                        ]
26
                    }
27
                },
28
                {
29
                    "label": "Photos",
30
                    "validation": {
31
                        "max_items": 3,
32
                        "min_items": 1
33
                    },
34
                    "name": "photos",
35
                    "type": "photos",
36
                    "required": true
37
                }
38
            ],
39
            "name": "sample_template"
40
        },
41
        {
42
            "id": "886abfe6-0068-48aa-988a-8639dad228c5",
43
            "content": [
44
                {
45
                    "type": "string",
46
                    "name": "OTP verification",
47
                    "label": "OTP",
48
                    "required": true
49
                },
50
                {
51
                    "type": "date_time",
52
                    "name": "Completion Time",
53
                    "label": "Completed at:",
54
                    "required": true
55
                }
56
            ],
57
            "name": "Sample_template_1"
58
        }
59
    ]
60
}

Delete a Document Template

This endpoint allows users to delete an existing document template using its unique ID.

DELETE

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

Request Parameters

Response Schema

Sample Request

1
curl --location --request DELETE 'https://api.nextbillion.io/fleetify/document_templates/886abfe6-0068-48aa-988a-8639dad228c5?key=<your_api_key>'

Sample Response

1
{
2
    "status": 200
3
}

API Query Limits

NextBillion.ai allows a maximum rate limit of 6000 queries per minute or 100 queries/second for continuous requests.
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.