Fleet API Documentation

Introduction

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.

Getting started

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.

Request & response

Successful Request

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. 

{…}

Invalid 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"}

Authentication

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}

Profile

POST /api/v1/user/profile

This endpoint returns details of the authenticated user. It returns a user object

User object

Field name Type Description
email 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

Request example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Token {TOKEN}" https://app.fleet.ke/api/v1/user/profile

Response example

{
	"email": [email protected],
	"first_name":"John",
	"last_name":"Doe"
}

Organizations

POST /api/v1/user/organizations

This endpoint returns a list of organizations your are a member. It returns an array of organization objects

Organization object

Field name Type Description
ID number The organization ID
name string The organization name

Request example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Token {TOKEN}" https://app.fleet.ke/api/v1/user/organizations

Response example

[
	{'ID': 1, 'name': 'Out & About Limited'},
	{'ID': 2, 'name': 'Ten plus Ten Limited'}
]

Branches

Get /api/v1/branch/?organization_id={organization_id}

This endpoint returns a list of organization banches Branch objects

Branch object

Field name Type Description
ID number The branch's primary identifier
name string Branch name

Request example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Token {TOKEN}" https://app.fleet.ke/api/v1/branch/?organization_id={organization_id}

Response example

[
		{"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"}}
]

Adding a branch

POST /api/v1/branch/create

This endpoint allows you to create a new branch

Request parameters

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

Request example

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

Response example

	{
		"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"
		}
	}

Order tags

Get /api/v1/order/tags?organization_id={organization_id}

This endpoint returns a list of organization order tags Order tags objects

Order tag object

Field name Type Description
ID Number The order tag's primary identifier
name string Order tag name
Description string Order tag description

Request example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Token {TOKEN}" https://app.fleet.ke/api/v1/order/tags?organization_id={organization_id}

Response example

			{
				"count": "1",
				"page": 1,
				"items": [
					{
						"ID": 5,
						"name": "westlands_orders",
						"description": "sample description"
					}
				]
			}

Adding Order tag

POST /api/v1/order/tags_create

This endpoint allows you to create a new order tag

Request parameters

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

Request example

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

Response example

{

	"ID": 7,
	"name": "sampe tag",
	"description": "Sample description"

}

Uploading an order

POST /api/v1/order/create

This endpoint allows you to create a new order

Request parameters

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
  • Prepaid - 1
  • Postpaid cash - 2
  • Postpaid mobile money - 3
  • Credit - 4
  • Cheque - 5
  • Direct Bank Deposit - 6
pickup Place object Required Pickup details.
dropoff Place object Required Drop-off details.

Place object

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

Contact object

Field name Type Description
name string Required contact name
email string Optional contact email
phone_number number Required Contact phone number

Location object

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

Coordinates object

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

Item object

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

Request example

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

Order object

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

  • Newly submited order - 1
  • Waiting for driver to be assigned - 2
  • Driver re-assigned - 3
  • Picked up by driver - 4
  • Driver arrived at client - 5
  • Driver could not complete delivery - 6
  • Cargo delivered - 7
  • Cargo return by driver - 8
  • Cargo return by driver - 9
  • Cargo return by driver - 10
  • Cargo return by driver - 11
  • Cargo return by driver - 12
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

  • Prepaid - 1
  • Postpaid cash - 2
  • Postpaid mobile money - 3
  • Credit - 4
  • Check - 5
  • Direct Bank Deposit - 6
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 ornull 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

Rider object

Field name Type Description
ID number The rider's primary identifier
name string Rider's name
phone_number integer The rider's phone number

Order object example

{'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 an order

Get an order by Order ID

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

Request example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Token {TOKEN}"  https://app.fleet.ke/api/v1/order/{ORDER_ID}

Get an order by Order ref

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

Request example

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}

Cancel an order

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

Retrieveing your orders

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

  • Newly submited order - 1
  • Waiting for driver to be assigned - 2
  • Driver re-assigned - 3
  • Picked up by driver - 4
  • Driver arrived at client - 5
  • Driver could not complete delivery - 6
  • Cargo delivered - 7
  • Cargo return by driver - 8
  • Cargo return by driver - 9
  • Cargo return by driver - 10
  • Cargo return by driver - 11
  • Cargo return by driver - 12
Example requests
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

Retrieveing your order state

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)

POST Json
Param Details
Organization_id

(Required) Limit orders to that particular organization
State(array)

(Optional) Only get orders with the state param, accepted values are

  • Newly submited order - 1
  • Waiting for driver to be assigned - 2
  • Driver re-assigned - 3
  • Picked up by driver - 4
  • Driver arrived at client - 5
  • Driver could not complete delivery - 6
  • Cargo delivered - 7
  • Cargo return by driver - 8
Order_ids

(Optional) only get the status of orders with the order ids
Payment status

(Optional) the payment status for a particular order


  • Paid - 1
  • Partially paid - 2
  • Not paid - 3
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:

  • If you combine both state and order_ids, and payment status this will be interpreted as return orders within the order ids with the given state and payment status
  • If you dont include state and order ids,and payment satus this will be interpreted as return all orders within a given organization
  • Optional fields will not be considered in filter if they are excluded. For example if you do not include payments tatus, then all orders regardless of payment status will be returned

Post JSON example

                {
					"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
					]
                }
Response Json params
Param Details
ID

The order ID
State

The order state
Payment method Payment method for the order
  • Prepaid - 1
  • Postpaid cash - 2
  • Postpaid mobile money - 3
  • Credit - 4

Response example

		[
		    {
		    	"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"
		    },
	    ]

Setting up a callback URL

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





Tracking and order

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

Updating Order and Items Objects

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}/