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.

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

Loading..

Request Body

Loading..

Response Schema

Loading..

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

Loading..

Response Schema

Loading..

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

Loading..

Request Body

Loading..

Response Schema

Loading..

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

Loading..

Response Schema

Loading..

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

Loading..

Response Schema

Loading..

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

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

© 2024 NextBillion.ai all rights reserved.