Bookable Taxi Integration Guide

18 Apr 2024
6 Minutes to read
Contributors

Print
Share
Dark
Light
PDF

Bookable Taxi Integration Guide

Updated on 18 Apr 2024
6 Minutes to read
Contributors

Print
Share
Dark
Light
PDF

Article Summary

Share feedback

Thanks for sharing your feedback!

Integration Guide For Bookable Taxi

For existing Despatch APIs we will attempt to map the payload into our bookable interface. However the minimum information & functionality would be required from the API.

Minimum End User Details

UserId - A unique id representing the end user
PhoneNumber - A telephone number, usually mobile number
Name - the name of the end user.
Active Journey's
* JourneyId
* Status
* Pickup Date/Time
* Pickup Location
* Drop Off Location(s)

Minimum API Functionality

Get User Details
Book a journey
Cancel a journey
Get Status of a journey

Recommended API

For Despatch designing a new API to enable Bookable, we recommend the following specification.

Despatch software may return some or all of this data. We incremently build out the end user experience based on the completeness of the response.

For example, if the location is present, and the channel is WhatsApp, when a user requests a status of their journey, or the status or journey changes, we will send a WhatsApp location message.

If Vehicle and Driver payloads are available then we will pass this information onto customer. If a driver has arrived and a driver phone number is present, we give the option to the end user to let the driver know they are "Coming Now"

Features such as Coming Now and details such as Driver name, badgeNumber, Vehicle description, registration can all be toggled on or off in the plugin settings per customer requirements.
No phone numbers are exposed to end user or driver at any time.

Authentication

We leave this up to the 3rd party to determine what is best for their use case.

POST /config

Request Body

This will be invoked on initation of each customer request

{
   "data" : { 
        "features" : [ "voice", "whatsapp" ]
        "options": [
            "jobID",
            "vehicle",
            "vehicleReg",
            "eta",
            "driverName",
            "comingNow",
            "callDriver",
            "cancel"
	  ],
      "skipDropOff": false,
    ...
   }
}

Property	Description	Required?
data	Taxi data object which is set on the plugin which will be passed to the 3rd party endpoint	false

Response Body

{
  "status" : "enabled",
  "eta" :  {
       "value" : 10,
       "unit" : "minutes"
  },
   "data" : {  ... }
}

Property	Description	Required?
status	current system status	true
eta	ETA estimated time of arrival	false
data	Taxi data object, fields returned in this payload will overwrite the static configuration allowing 3rd party to turn on/off features, languages etc	false

POST /user

Request Body

{
  "phoneNumber" : "447777777777",
  "data" : {
     "companyName": "My Taxi Company",
     "activeBookings" : "true"
     ...
  }
}

Property	Description	Required?
phoneNumber	The end users phone number in E164 format. For example 447777777777	true
data	Taxi data which is set on the plugin which will be passed to the 3rd party endpoint	false

Response Body

{
    "userId" : "user1234",
    "phoneNumber" : "44777777777",
    "name" :  "John Smith",
    "status" : "ENABLED",
    "data" :  {
        "features" : [ "whatsapp" ],
        "options": [
            "jobID",
            "vehicle",
            "vehicleReg",
            "eta",
            "driverName"
	    ],
        "skipDropOff": true,
    },
    "activeBookings" : [
        {
            "journeyId" : "2468",
            "status" : "ACCEPTED",
            "eta" :  {
                "value" : 10,
                "unit" : "minutes"
            },
            "price" :  {
                "value" : 9.99,
                "currency" : "GBP",
                "type" : "ESTIMATE"
            },
            "date" : "2023-10-07T19:35:33.801+00:00",
            "pickup": {
                "address" : "1 Kings Rd, Brighton and Hove, Brighton BN1 2FA",
                "location" : {
                     "longitude" : 50.82137100634119,
                     "latitude" :  -0.14762783092575613
                }
            },
            "dropoffs": [
                {
                    "address" : "52-55 Trafalgar St, Brighton and Hove, Brighton BN1 4EB",
                    "location" : {
                         "longitude" :50.82859562173957,
                         "latitude" :  -0.14083647771680116
                    }
                }
            ],
            "passenger" : {
                 "phoneNumber" : "44777777777",
                 "name" :  "John Smith",
            },
            "vehicle" : {
                "description" : "White Toyota",
                "registration" : "WV60 FLL"
            },
            "driver" : {
                "name" :  "Joe Schmoe",
                "phoneNumber" : "447888888888",
                "badgeNumber" : "1234"
            },
            "location" : {
                "longitude" : 50.8188111828403, 
                "latitude" : -0.13869175552866123
            }
        }
    ]
}

Property	Description	Required
userId	end user id	true
phoneNumber	end user phone number	true
name	end user name	true
status	status of end user : ENABLED, DISABLED, BLACKLISTED	false
features	array of user features overrides	false
activeBookings	array of Journey	false

POST /book

Request Body

{
   "userId" : "user1234",
   "name" : "John Smith",
   "phoneNumber" :  "44777777777",
   "pickup" : {
     "address" : "1 Kings Rd, Brighton and Hove, Brighton BN1 2FA",
     "location" : {
        "longitude" : 50.82137100634119,
        "latitude" :  -0.14762783092575613
     }
  },
   "dropoffs": [
        {
            "address" : "52-55 Trafalgar St, Brighton and Hove, Brighton BN1 4EB",
            "location" : {
                 "longitude" :50.82859562173957,
                 "latitude" :  -0.14083647771680116
            }
        }
   ],
   "pickupTime" : "2023-10-08T20:00:00.000+00:00",
   "vehicleCategory" : "Saloon",
   "data" : { ... }
}

Property	Description	Required
journeyId	if present then edit booking, null value will create booking	false
userId	user id (if known)	false
name	name of passenger	true
phoneNumber	end users phone number in E164 format	true
pickup	Address the pickup address	true
dropoffs	Array of Address the destination addresses	true (at least 1)
pickupTime	ISO 8601 formatted date string	true
vehicleCategory	type of vehicle	false
data	arbitory data which can be set on the plugin which will be passed to the 3rd party endpoint	false

Response Body

{
    "journeyId": "2468",
    "status" : "ACCEPTED"
    ...
}

Property	Description	Required
journeyId	the journey id	true
status	the current status	true

POST /cancel

Request Body

{
    "userId" : "user1234"
    "journeyId" : "2468",
}

Property	Description	Required
userId	the user id	true
name	the journey id	true

Response Body

{
    "journeyId": "2468",
    "status" : "CANCELLED",
    ...
}

Property	Description	Required
journeyId	the journey id	true
status	the current status	true

POST /status

Request Body

{
    "userId" : "user1234"
    "journeyId" : "2468",
}

Property	Description	Required
userId	the user id	true
name	the journey id	true

Response Body

{
            "journeyId" : "2468",
            "status" : "EN_ROUTE",
            "eta" :  {
                "value" : 10,
                "unit" : "minutes"
            },
            "price" :  {
                "value" : 9.99,
                "currency" : "GBP",
                "type" : "ESTIMATE"
            },
            "pickup": {
                "address" : "1 Kings Rd, Brighton and Hove, Brighton BN1 2FA",
                "location" : {
                     "longitude" : 50.82137100634119,
                     "latitude" :  -0.14762783092575613
                }
            },
            "dropoffs": [
                {
                    "address" : "52-55 Trafalgar St, Brighton and Hove, Brighton BN1 4EB",
                    "location" : {
                         "longitude" :50.82859562173957,
                         "latitude" :  -0.14083647771680116
                    }
                }
            ],
            "passenger" : {
                 "phoneNumber" : "44777777777",
                 "name" :  "John Smith",
            },
            "vehicle" : {
                "description" : "White Toyota",
                "registration" : "WV60 FLL"
            },
            "driver" : {
                "name" :  "Joe Schmoe",
                "phoneNumber" : "447888888888",
                "badgeNumber" : "1234"
            },
            "location" : {
                "longitude" : 50.8188111828403, 
                "latitude" : -0.13869175552866123
            }
        }

Property	Description	Required
journeyId	the journey id	true
status	the current status	true
See Journey Object

Objects

Journey Object

Property	Description	Required
journeyId	journey id	true
date	ISO 8601 formatted date string	true
status	current status of journey. see Valid Statuses	true
eta	ETA estimated time of arrival	false
price	Price the journey price	false
pickup	Address the pickup address	true
dropoffs	Array of Address the destination addresses	true
passenger	Passenger may be a different value to the end user	false
vehicle	Vehicle the vehicle details	false
driver	Driver the driver details	false
location	Point current location of vehicle	false

ETA Object

Property	Description	Required
value	amount of time	true
unit	unit of measure, for example "minutes"	true

Price Object

Property	Description	Required
value	price amount	true
currency	price currency	true
type	enum - ESTIMATED, FIXED, MINIMUM, MAXIMUM	false

Address Object

Property	Description	Required
address	full address including postcode	true
location	Point coordinates	true

Passenger Object

Property	Description	Required
phoneNumber	passenger phone number	true
name	passengerr name	true

Vehicle Object

Property	Description	Required
description	description of vehicle	true
registration	number plate of vehicle	true

Driver Object

Property	Description	Required
name	name of driver	true
phoneNumber	phoneNumber of driver	true
badgeNumber	registered badge number of driver	true

Point Object

Property	Description	Required
longitude	x	true
latitude	y	true

Valid Journey Statuses

Status	Description
HELD	Journey has been held by despatch
WAITING	Journey is waiting to be allocated to driver
ACCEPTED	Journey has been accepted by driver
EN_ROUTE	Vehicle is en route
ARRIVED	Vehicle has arrived
POB	Passenger is on board vehicle
COMPLETE	Journey has completed

Table of contents

Integration Guide For Bookable Taxi
POST /config
POST /user
POST /book
POST /cancel
POST /status
Valid Journey Statuses