Welcome to the FLEET API documentation.
The FLEET API is a RESTful API that allows you to manage your orders in a simple, programmatic way using conventional HTTP requests, allowing you to easily make calls to create, view and update your orders.
If you have not already done so. Login in to your account and go to https://app.fleet.ke/accounts/developers to obtain an API token.
A successfull request will return a JSON object with HTTP status code 200, You can make both GET or POST requests
Here is an example of a successfull request.
{…}
A invalid request will return a JSON object with HTTP status code 400 and details about the error
Here is an example of an invalid request.
{"detail":"Error message"}
All requests must be authenticated using a token. You can obtain a token from https://app.fleet.ke/accounts/developers
Making an authenticated request
curl -X POST -H "Content-Type: application/json" -H "Authorization: Token {TOKEN}" https://app.fleet.ke/api/v1/{ENDPONT}
POST /api/v1/user/profile
This endpoint returns details of the authenticated user. It returns a user object
Field name | Type | Description |
---|---|---|
string |
The authenticated users email. | |
first_name | string or null |
The authenticated users first name if available or null is not avaliable |
last_name | string or null |
The authenticated users last name if available or null is not avaliable |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Token {TOKEN}" https://app.fleet.ke/api/v1/user/profile
{ "email": [email protected], "first_name":"John", "last_name":"Doe" }
POST /api/v1/user/organizations
This endpoint returns a list of organizations your are a member. It returns an array of organization objects
Field name | Type | Description |
---|---|---|
ID | number |
The organization ID |
name | string |
The organization name |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Token {TOKEN}" https://app.fleet.ke/api/v1/user/organizations
[ {'ID': 1, 'name': 'Out & About Limited'}, {'ID': 2, 'name': 'Ten plus Ten Limited'} ]
Get /api/v1/branch/?organization_id={organization_id}
This endpoint returns a list of organization banches Branch objects
Field name | Type | Description |
---|---|---|
ID | number |
The branch's primary identifier |
name | string |
Branch name |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Token {TOKEN}" https://app.fleet.ke/api/v1/branch/?organization_id={organization_id}
[ {"ID": 7,"name": "Kisumu","country": "Kenya","location": "Kisumu", "is_active": true,"created": "2023-01-18T12:10:15.230608+00:00", "timezone": "Africa/Nairobi","lat": -0.0995176000000000,"lng": 34.7578511999999900, "added_by": {"ID": 2,"name": "XXXXXX"}} ]
POST /api/v1/branch/create
This endpoint allows you to create a new branch
Field name | Type | Description |
---|---|---|
organization_id | number |
Required the organization uploading the order |
name | string |
Required the names of the branch |
country | string |
RequiredThe country the branch belongs to |
location | string |
Required Location of the branch within the country |
lat | float |
Optional Location latitude |
lng | float |
Optional Location longitude |
timezone | string |
optionalTimezone of country the branch belongs to |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Token {TOKEN}" -d '{ "name": "kitale5", "country": "Kenya", "location": "Kitale", "organization_id":2, "timezone": "Africa/Nairobi", "lat": 1.019089, "lng": 35.0023048 }' https://app.fleet.ke/api/v1/branch/create
The response will be a JSON object with the newly created branch
{ "ID": 13, "name": "kitale", "country": "Kenya", "location": "Kitale", "is_active": true, "created": "2023-01-20T03:55:30.638880+00:00", "timezone": "Africa/Nairobi", "lat": 1.019089, "lng": 35.0023048, "added_by": { "ID": 2, "name": "okeyo" } }
Get /api/v1/order/tags?organization_id={organization_id}
This endpoint returns a list of organization order tags Order tags objects
Field name | Type | Description |
---|---|---|
ID | Number |
The order tag's primary identifier |
name | string |
Order tag name |
Description | string |
Order tag description |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Token {TOKEN}" https://app.fleet.ke/api/v1/order/tags?organization_id={organization_id}
{ "count": "1", "page": 1, "items": [ { "ID": 5, "name": "westlands_orders", "description": "sample description" } ] }
POST /api/v1/order/tags_create
This endpoint allows you to create a new order tag
Field name | Type | Description |
---|---|---|
organization_id | number |
Required the organization id |
name | string |
Required the name of the order tag |
description | string |
OptionDescription of order tag |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Token {TOKEN}" -d '{ "name": "sample tag", "description": "Sample description", }' https://app.fleet.ke/api/v1/order/tags_create
The response will be a JSON object with the newly created branch
{ "ID": 7, "name": "sampe tag", "description": "Sample description" }
POST /api/v1/order/create
This endpoint allows you to create a new order
Field name | Type | Description |
---|---|---|
organization_id | number |
Required the organization uploading the order |
branch_id | number |
Optional the branch the order belongs to |
start_delivery_datetimetime_window | datetime (FORMAT date.month.year hour:min) |
Optional Time Window 1 |
end_delivery_datetimetime_window | datetime (FORMAT date.month.year hour:min) |
Optional Time Window 2 |
priority | number |
Optional A number between 0 and 100 |
skills | number |
Optional the Skills/special conditions that the order vehicle must have |
order_tag_ids | Array |
Optional an array of order tags |
order_ref | string |
optional Order ref of the order, must be unique |
order_sid | string |
optional Order sid(site ID) of the order, must be unique |
otp_code_forced | int (should either be 1 or 0. Any number is regarded as zero) |
optional Whether to enforce otp for this order on arrival to customer. If 1, the otp must be verified else no a must |
price | string float |
optional cargo price |
weight | string float |
optional cargo weight |
length | string float |
optional cargo length |
width | string float |
optional cargo width |
height | string float |
optional cargo height |
payment_method | number |
optional payment method for the order
|
pickup | Place object | Required Pickup details. |
dropoff | Place object | Required Drop-off details. |
Field name | Type | Description |
---|---|---|
contact | Contact object | Required The contact details |
location | Location object | Required The location details |
notes | string |
Optional Any notes extra information |
Field name | Type | Description |
---|---|---|
name | string |
Required contact name |
string |
Optional contact email | |
phone_number | number |
Required Contact phone number |
Field name | Type | Description |
---|---|---|
addresss | string |
Required The name of the location (typo has persisted for backward compatibility) |
apartment | string |
Optional Road/Apartment/Hse. No |
coords | Coordinates object | Required The coordinates of the location |
Field name | Type | Description |
---|---|---|
lat | number float |
Required The latitudinal coordinates of the delivery location |
lng | number float |
Required The longitudial coordinates of the delivery location |
Field name | Type | Description |
---|---|---|
name | string |
Required The name of the item |
price | string |
Required Item price |
length | string or null |
Item length |
width | string or null |
Item width |
height | string or null |
Item price |
quantity | string |
Required Item quantity |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Token {TOKEN}" -d '{ 'organization_id' : 1, 'branch_id':2, "start_delivery_datetimetime_window":"23.01.2023 22:32", "end_delivery_datetimetime_window":"20.1.2023 22:32", "priority":"20", "otp_code_forced":1, "skills":"2", 'order_tag_ids':['5','4'], 'order_ref' : 'GB12345', 'order_sid' : 'GB12GG5', 'pickup' : { 'location' : { 'addresss' : 'House of the hill', 'apartment' : 'The Manor RD, Hse no. 1', 'coords' : { 'lat': -1.254766, 'lng': 36.797427 } }, 'contact' : { 'name' : 'John Doe', 'email' : '[email protected]', 'phone_number' : '254799999999' }, 'notes' : 'Beware of dogs' }, 'dropoff' : { 'location' : { 'addresss' : 'House of the hill', 'apartment' : 'The Manor RD, Hse no. 2', 'coords' : { 'lat': -1.354766, 'lng': 36.497427 } }, 'contact' : { 'name' : 'Jane Doe', 'email' : '[email protected]', 'phone_number' : '254711111111' }, 'notes' : 'Beware of dogs' }, 'price' : 1.1, 'length': 1.2, 'width': 1.3, 'height': 1.4, 'weight': 1.5, 'payment_method' : 1, 'sla': 'tst', 'items': [ { "name": "Indiana Biryani Rice - 25kg", "price": 2350.0, "length": 4.1, "width": 3.0, "height": 2.3, "quantity": 2.1 } ] }' https://app.fleet.ke/api/v1/order/create
The response will be a JSON object with the newly created order
Field name | Type | Description |
---|---|---|
ID | number |
A unique identifier of the order |
ref | string |
Order reference |
state | integer |
Integer encoded value of the current state of the order
filters your orders by state, accepted values are
|
state_display | string |
Current state of the order |
notes | string |
Any notes about the order |
tracking_code | string |
A code that can be used to tack the order |
payment_method | integer |
Integer encoded value of the payment method
filters your orders by state, accepted values are
|
payment_method_display | string |
The payment method of the order |
paid | boolean |
Payment status of the order |
signature | string or null url |
Signature collected from customer when order is complete |
signature_name | string or null float |
The Name of the receiver of the order |
pod_images | Array of string or null url |
Images collected upon delivery |
price | string or null float |
cargo price |
weight | string or null float |
cargo weight |
length | string or null float |
cargo length |
width | string or null float |
cargo width |
height | string or null float |
cargo height |
pickup | Place object | Pickup details. |
dropoff | Place object | Drop-off details. |
branch | Branch object
or |
Branch details. |
tags | Order tag object array
or |
tags. |
review | string or null |
Customer review |
rating | number or null float |
Customer rating for the driver |
order_rating | number or null float |
Customer rating for the order |
order_rating | number or null float |
Customer rating for the order |
job_number | number or null float |
Sequence Number of the job for the Driver. If the order is not on route, it is assigned as 1/1 else it is assigned as (Sequence_number) / (total jobs on that route) |
route_id | number or null float |
It is the ID for the route in which this order object belongs to. If it is does not belong to route it is null |
rider | Rider object | Details of the rider assigned to the order |
items | [] or null |
A list of Item Objects |
created | string |
Date the order was uploaded yyyy-MM-dd HH:mm:ss.SSSZ e.g. 2020-10-28 18:36:50.571476+00:00 |
modified | string |
Date the order was last updated yyyy-MM-dd HH:mm:ss.SSSZ e.g. 2020-10-28 18:36:50.571476+00:00 |
ETA | string |
Date for the Estimated Arrival yyyy-MM-dd HH:mm:ss.SSSZ e.g. 2020-10-28 18:36:50.571476+00:00 |
datetime_ordered | string |
Date the order was ordered by the customer yyyy-MM-dd HH:mm:ss.SSSZ e.g. 2020-10-28 18:36:50.571476+00:00 |
datetime_failed | string or null |
Date the order marked as failed yyyy-MM-dd'T'HH:mm:ssZ e.g. 2020-10-28T18:36:50.571476+00:00 |
datetime_reviewed | string or null |
Date the order reviewed by the customer yyyy-MM-dd'T'HH:mm:ssZ e.g. 2020-10-28T18:36:50.571476+00:00 |
datetime_completed | string or null |
Date the order marked as completed yyyy-MM-dd'T'HH:mm:ssZ e.g. 2020-10-28T18:36:50.571476+00:00 |
datetime_failed | string or null |
Date the order marked as failed yyyy-MM-dd'T'HH:mm:ssZ e.g. 2020-10-28T18:36:50.571476+00:00 |
sla | string or null |
A string for the organization's sla short code (case-insensitive), for instance tst |
Field name | Type | Description |
---|---|---|
ID | number |
The rider's primary identifier |
name | string |
Rider's name |
phone_number | integer |
The rider's phone number |
{'ID': 203, 'ref': 'GBT1-2021513145743', 'tracking_code': '8db2deb244c250dbae190d6cb8848d09', 'state': 3, 'state_display': 'Driver Assigned', 'notes': None, 'payment_method': 1, 'payment_method_display': 'Prepaid', 'paid': True, 'modified': '2021-05-13T14:55:05.181956+00:00', 'created': '2021-05-13T11:57:43.188317+00:00', 'signature': None, "signature_name":None, 'pod_images': None, 'datetime_failed': None, 'datetime_ordered': '2021-05-13T11:57:43.181683+00:00', 'ETA': '2023-04-13T10:36:14.342149+00:00', 'datetime_reviewed': None, 'datetime_completed': None, 'price': '1.10', 'width': '1.30', 'weight': '1.50', 'length': '1.20', 'height': '1.40', 'pickup': {'location': {'address': 'House of the Hill', 'apartment': 'The Manor, House 2', 'coords': {'lat': '-1.3547660000000000', 'lng': '36.8974269999999990'}}, 'contact': {'name': 'John Doe', 'email': '[email protected]', 'phone_number': 254111111111}, 'notes': 'Beware of dogs'}, 'dropoff': {'location': {'address': 'House on the Hill', 'apartment': 'The Manor', 'coords': {'lat': '-1.6547660000000000', 'lng': '36.5974269999999990'}}, 'contact': {'name': 'Jane Doe', 'email': '[email protected]', 'phone_number': 254222222222}, 'notes': 'Beware of dogs'}, 'review': None, 'rating': None, 'rider': {'ID': 7, 'name': 'John Doe', 'phone_number': 254999999999}, 'vehicle_type': 0, 'tracking_code':"00000000000000000000000000021bfa", 'vehicle_type_display': 'TBD', 'preffered_delivery_date': '2021-05-03', 'preffered_delivery_period': 1, 'preffered_delivery_period_display':'Anytime', "job_number": "1/1", "route_id": null, 'branch': {'ID': 3,'name': 'kisumu_branch'}, "tags": [ { "ID": 5, "name": "sample tag", "description": "sample description" } ], }
GET /api/v1/order/{ORDER_ID}
With the order ID you can request details about the order using its ID
The response will be an order object with order details is available
curl -X GET -H "Content-Type: application/json" -H "Authorization: Token {TOKEN}" https://app.fleet.ke/api/v1/order/{ORDER_ID}
GET /api/v1/order/by-ref?order_ref={ORDER_REF}&organization_id={ORGANISATION_ID}
With the order ID you can request details about the order using its ID
The response will be an order object with order details is available
curl -X GET -H "Content-Type: application/json" -H "Authorization: Token {TOKEN}" https://app.fleet.ke/api/v1/order/by-ref?order_ref={ORDER_REF}&organization_id={ORGANISATION_ID}
POST /api/v1/order/{ORDER_ID}/cancel
This endpoint allows you to cancel and order
curl -X POST -H "Content-Type: application/json" https://app.fleet.ke/api/v1/order/{ORDER_ID}/cancel
GET /api/v1/order
The endpiont allows you get your orders based on your search criteria
curl -X GET -H "Content-Type: application/json" https://app.fleet.ke/api/v1/order
The response will be a JSON object with your orders
Param | Details |
---|---|
s | Search order by customer, rider, order ref |
page | filter by page number, default is 1 |
per_page | number of orders to return per page |
state |
filters your orders by state, accepted values are
|
curl -X GET -H "Content-Type: application/json" https://app.fleet.ke/api/v1/order
curl -X GET -H "Content-Type: application/json" https://app.fleet.ke/api/v1/order?state=1
POST /api/v1/order/order_state
The endpiont allows you get your organization order state
curl -X POST -d '{"organization_id":"2","payment_status":"1","start_datetime":"2023-02-24T01:00:00+0300","end_datetime":"2023-02-24T04:11:00+0300", "state":"1","order_ids":["1","2","3","4"]}' -H "Content-Type: application/json" https://app.fleet.ke/api/v1/order/order_state
The response will be a JSON object with your orders(id,state)
Param | Details |
---|---|
Organization_id | (Required) Limit orders to that particular organization |
State(array) | (Optional) Only get orders with the state param, accepted values are
|
Order_ids | (Optional) only get the status of orders with the order ids |
Payment status | (Optional) the payment status for a particular order
|
Start/End Date Time | (Optional) only get the orders modified between the datetime period, This field must be in the format %Y-%m-%dT%H:%M:%S%Z |
Note:
{ "organization_id":2, "state":[1,2], "start_datetime":"2023-02-24T01:00:00+0300", "end_datetime":"2023-02-24T04:11:00+0300", "payment_status":1, "order_ids":[ 25565,25566,25567,25568 ] }
Param | Details |
---|---|
ID | The order ID |
State | The order state |
Payment method | Payment method for the order
|
[ { "id": 25565, "state": 1, "payment_method": 3, "total_amount": 456.0, "total_paid": 0.0, "receipt_number": null }, { "id": 25567, "state": 1, "payment_method": 1, "total_amount": 217.0, "total_paid": 217.0, "receipt_number": "MT3TYDFEA" }, ]
The callback URL allows you to recieve updates on an order every time it is updated.
A HTTP POST request with the new order object is sent to your callback when the order changes
Get the tracking code in order object ie 88d2a5e690905ec6857d5ad5a9366049
Append the tacking code at the end of this url: https://analytics.fleet.ke/tracking ie https://analytics.fleet.ke/tracking/88d2a5e690905ec6857d5ad5a9366049
To update an order, send a PUT
request to the following endpoint:
/api/v1/order/{order_id}/update/
NOTE: In above you need to set Authorization headers as Token xxxxxxxxx where xxxx is your accounts token
The request body should contain a dictionary with the updated order details. You can also use get for the same above endpoint to get items that you can copy and use to update. Here's an example:
{ "end_delivery_datetimetime_window": null, "start_delivery_datetimetime_window": null, "customer_first_name": null, "customer_last_name": null, "customer_phone_number": null, "customer_email": null, "dropoff_location_details": "", "dropoff_location_name": "Jebel Ali - Dubai - United Arab Emirates", "dropoff_contact_phone_number": 254798355947, "dropoff_contact_name": "DDD KK", "dropoff_contact_email": "[email protected]", "dropoff_location_name_more": "Sabugo", "dropoff_lat": "24.9857145000000000", "dropoff_lng": "55.0272904000000000", "weight": null, "state": 1, "payment_method": 1, "pickup_location_details": "", "pickup_location_name": "Kisumu International Airport, Kisumu, Kenya", "pickup_contact_phone_number": 25471234566, "pickup_contact_name": "Su", "pickup_contact_email": "[email protected]", "pickup_location_name_more": "Kitale", "pickup_lat": "-0.0819301000000000", "pickup_lng": "34.7285916000000000", "items": [ { "name": "Indiana Biryani Rice - 25kg", "price": "2350.00", "width": "7.00", "weight": null, "length": "5.00", "height": "6.00", "quantity": 13 } ] }
In the request body, the items
field contains a list of items to be updated. If an item does not have an ID, it will be treated as a new item and created. Otherwise, the values of the existing item will be updated.
Important Note: The state
field can only be updated to 1
or 2
. Any other state value will result in a validation error.
If the update is successful, the API will return a 200 OK
response. If there are any errors, the response will contain the corresponding error messages.
To retrieve the order object, you can send a GET
request to the same endpoint without the /update/
suffix.
api/v1/order/{order_id}/