Taxi Supplier API

Home

References

Retrieve all bookings

Provides details for all bookings assigned to the connected supply partner, with pagination.

GET /v1/bookings

Request

URL Parameters

Parameter Description Required
status Pass an optional comma-delimited list of statuses to filter bookings by status:
NEW
ACCEPTED
DRIVER_ASSIGNED
PENDING_AMENDMENT
PENDING_CANCELLATION

We will return all bookings by default.		 No
size Retrieve the specified number of bookings per page, we will return 400 bookings per page by default. The maximum value allowed here is 500. No
pickUpDateFrom Retrieve all bookings from the given datetime in UTC (ISO 8601). By default, this will default to the start of the day yesterday. No
pickUpDateTo Retrieve all bookings to the given datetime in UTC (ISO 8601). No

Sample Request

GET /v1/bookings?status=ACCEPTED&pickUpDateFrom=2020-07-08T00%3A00%3A00

Response

Warning

customerReference is equivalent to reference and bookingReference is equivalent to legId. Please note reference and legId will be deprecated in a future version of the API.

Important Notice: The pickup_date_time returned in the all bookings and single booking retrieval may be different to the original search webhook request. This is due to the addition of flight number details or customer requests post search. The information given in the booking retrieval should be used.

Field Type Description
customerReference String The customer reference.
bookingReference String The booking reference.
state_hash String The latest state hash for the booking (read more).
status String The status of the booking (read more).
searchResultId String A UUID representing the search result with a maximum length of 100 characters.
booked_date String The date the booking was placed.
flight_number String The flight number (airport pickups only).
pickup_date_time String The pickup timestamp in UTC (ISO 8601). The value of this may be different to the time provided in the search request.
pickup_date_time_zone String The pickup timezone in IANA format, used to convert the pickup_date_time to the local timezone.
vehicle_type String One of the following values:

STANDARD
LUXURY
EXECUTIVE
PEOPLE_CARRIER
LARGE_PEOPLE_CARRIER
EXECUTIVE_PEOPLE_CARRIER
MINIBUS
ELECTRIC_STANDARD
ELECTRIC_LUXURY
passenger_count Integer The number of passengers on the booking.
meet_and_greet Boolean Indicates whether meet & greet is required.
price.amount Float The supplier price for the booking (includes Meet and Greet amount where applicable). For CANCELLED, DECLINED or PENDING_CANCELLATION bookings, this will be 0 (currently for both refunded and non-refund bookings).
price.currency String The currency of the amount, in ISO 4217 format.
price.customerOriginalPrice Float The original price of booking before any discount is applied.
price.customerCurrency String The currency used by the customer to pay for their booking, in ISO 4217 format.
passenger.title String The lead passengers title.
passenger.name String The lead passengers full name.
passenger.telephone_number String The lead passengers phone number in E.164 format.
additional_comments String Additional comments/special requests provided by customer.
pickup|dropoff.latitude Float The locations latitude.
pickup|dropoff.longitude Float The locations longitude.
pickup|dropoff.address String The full address for the location.
pickup|dropoff.establishment_name String The name of the establishment. For example, the name of the hotel.
pickup|dropoff.postcode String The locations postcode.
pickup|dropoff.country String The locations country (ISO 3166 alpha-2).
pickup|dropoff.type String One of the following values:

AIRPORT
STREET_ADDRESS
INTERSECTION
PREMISE
POSTAL_CODE
POINT_OF_INTEREST

Note

The example below shows a single example booking, it's likely in reality you would have several bookings in the array and possibly multiple pages. It's also important to note that bookings with status COMPLETE won't be returned and bookings will be set to COMPLETE 6 hours after pickup time. The get single booking endpoint can be used to retrieve with status COMPLETE.

HTTP 200 - OK

{
    "links": [
        {
            "rel": "next",
            "href": "/v1/bookings?size=400&after=1646757553000",
            "type": "GET"
        }
    ],
    "bookings": [
        {
            "links": [
                {
                    "rel": "self",
                    "href": "/v1/bookings/46825434/34745155",
                    "type": "GET"
                },
                {
                    "rel": "accept",
                    "href": "/v1/bookings/46825434/34745155/responses",
                    "type": "POST"
                },
                {
                    "rel": "reject",
                    "href": "/v1/bookings/46825434/34745155/responses",
                    "type": "POST"
                }
            ],
            "reference": "46825434",
            "customerReference": "46825434",
            "legId": "34745155",
            "bookingReference": "34745155",
            "state_hash": "8904f18fa3c66e925b4864fae263a52180da38bb358f78abda018adf99eb56d2",
            "status": "NEW",
            "searchResultId": "3948465738756348",
            "price": {
                "amount": "24.72",
                "currency": "EUR",
                "customerOriginalPrice": 32.00,
                "customerCurrency": "GBP"
            },
            "booked_date": "2022-03-09T10:58:30",
            "pickup_date_time": "2022-03-12T18:30:00",
            "pickup_date_time_zone": "Europe/Rome",
            "vehicle_type": "STANDARD",
            "passenger_count": 2,
            "flight_number": "FR6835",
            "meet_and_greet": true,
            "meet_and_greet_message": "Free text customer message",
            "passenger": {
                "title": "ms",
                "name": "Gillian Tans",
                "telephone_number": "+447545485868"
            },
            "pickup": {
                "latitude": 40.877554,
                "longitude": 14.282728,
                "address": "Capodichino - Naples International Airport (NAP), Viale F. Ruffo di Calabria, 80144 Napoli NA, Italy",
                "establishment_name": "Capodichino - Naples International Airport (NAP)",
                "postcode": "80144",
                "country": "IT",
                "type": "Airport"
            },
            "dropoff": {
                "latitude": 40.8281144,
                "longitude": 14.2192266,
                "address": "Demart Suites, Piazzetta Leone a Mergellina, 2, 80122 Napoli NA, Italy",
                "establishment_name": "Demart Suites",
                "postcode": "80122",
                "country": "IT",
                "type": "GEO"
            }
        }
    ]
}

HTTP 400 - Bad Request

{
  "message": "Invalid Input parameter",
  "description": "Invalid date-time format for pickUpDateFrom or pickUpDateTo"
}

HTTP 401 - Unauthorized

{
  "message": "Invalid Authorization Token",
  "description": "Invalid authorization token in header"
}

HTTP 429 - Too Many Requests

{
  "message": "Rate limit exceeded",
  "description": "You have exceeded your allocated limit for requests on this endpoint, please wait before calling it again"
}

Retrieve a single booking

Provides details of a single booking assigned to the connected supply partner.

GET /v1/bookings/:customerReference/:bookingReference

Response

Warning

customerReference is equivalent to reference and bookingReference is equivalent to legId. Please note reference and legId will be deprecated in a future version of the API.

Important Notice: The pickup_date_time returned in the all bookings and single booking retrieval may be different to the original search webhook request. This is due to the addition of flight number details or customer requests post search. The information given in the booking retrieval should be used.

Field Type Description
customerReference String The customer reference.
bookingReference String The booking reference.
state_hash String The latest state hash for the booking (read more).
status String The status of the booking (read more).
searchResultId String A UUID representing the search result with a maximum length of 100 characters.
booked_date String The date the booking was placed.
pickup_date_time String The pickup timestamp in UTC (ISO 8601). The value of this may be different to the time provided in the search request.
pickup_date_time_zone String The pickup timezone in IANA format, used to convert the pickup_date_time to the local timezone.
flight_number String The flight number (airport pickups only).
vehicle_type String One of the following values:

STANDARD
LUXURY
EXECUTIVE
PEOPLE_CARRIER
LARGE_PEOPLE_CARRIER
EXECUTIVE_PEOPLE_CARRIER
MINIBUS
ELECTRIC_STANDARD
ELECTRIC_LUXURY
passenger_count Integer The number of passengers on the booking.
meet_and_greet Boolean Indicates whether meet & greet is required.
price.amount Float The supplier price for the booking (includes Meet and Greet amount where applicable). For CANCELLED, DECLINED or PENDING_CANCELLATION bookings, this will be 0 (currently for both refunded and non-refund bookings).
price.currency String The currency of the amount, in ISO 4217 format.
price.customerOriginalPrice Float The original price of booking before any discount is applied.
price.customerCurrency String The currency used by the customer to pay for their booking, in ISO 4217 format.
passenger.title String The lead passengers title.
passenger.name String The lead passengers full name.
passenger.telephone_number String The lead passengers phone number in E.164 format.
pickup|dropoff.latitude Float The locations latitude.
pickup|dropoff.longitude Float The locations longitude.
pickup|dropoff.address String The full address for the location.
pickup|dropoff.establishment_name String The name of the establishment. For example, the name of the hotel.
pickup|dropoff.postcode String The locations postcode.
pickup|dropoff.country String The locations country (ISO 3166 alpha-2).
pickup|dropoff.type String One of the following values:

AIRPORT
STREET_ADDRESS
INTERSECTION
PREMISE
POSTAL_CODE
POINT_OF_INTEREST

HTTP 200 - OK

Note

The booking status will determine what actions are possible. For example, you cannot reject a booking with a status of "CANCELLED".


{
    "links": [
        {
            "rel": "self",
            "href": "/v1/bookings/46825434/34745155",
            "type": "GET"
        },
        {
            "rel": "reject",
            "href": "/v1/bookings/46825434/58782517/34745155",
            "type": "POST"
        }
    ],
    "reference": "46825434",
    "customerReference": "46825434",
    "legId": "34745155",
    "bookingReference": "34745155",
    "state_hash": "8904f18fa3c66e925b4864fae263a52180da38bb358f78abda018adf99eb56d2",
    "status": "NEW",
    "searchResultId": "3948465738756348",
    "price": {
        "amount": "24.72",
        "currency": "EUR",
        "customerOriginalPrice": 32.00,
        "customerCurrency": "GBP"
    },
    "booked_date": "2022-03-09T10:58:30",
    "pickup_date_time": "2022-03-12T18:30:00",
    "pickup_date_time_zone": "Europe/Rome",
    "vehicle_type": "STANDARD",
    "passenger_count": 2,
    "flight_number": "FR6835",
    "meet_and_greet": true,
    "meet_and_greet_message": "Free text customer message",
    "passenger": {
        "title": "ms",
        "name": "Gillian Tans",
        "telephone_number": "+447545485868"
    },
    "pickup": {
        "latitude": 40.877554,
        "longitude": 14.282728,
        "address": "Capodichino - Naples International Airport (NAP), Viale F. Ruffo di Calabria, 80144 Napoli NA, Italy",
        "establishment_name": "Capodichino - Naples International Airport (NAP)",
        "postcode": "80144",
        "country": "IT",
        "type": "Airport"
    },
    "dropoff": {
        "latitude": 40.8281144,
        "longitude": 14.2192266,
        "address": "Demart Suites, Piazzetta Leone a Mergellina, 2, 80122 Napoli NA, Italy",
        "establishment_name": "Demart Suites",
        "postcode": "80122",
        "country": "IT",
        "type": "GEO"
    }
}

HTTP 401 - Unauthorized

{
  "message": "Invalid Authorization Token",
  "description": "Invalid authorization token in header"
}

HTTP 404 - Not Found

{
  "message": "Not Found",
  "description": "Booking Not Found"
}

Accept or reject a booking

Enables you to ACCEPT or REJECT your allocated bookings, read more information about our booking statuses & transitions and cancellation reasons.

POST /v1/bookings/:customerReference/:bookingReference/responses

Request

Field Type Description Required
supplierResponse String One of either: (read more about booking statuses & transitions)

ACCEPT
REJECT		 Yes
state_hash String The state hash retrieved from the latest version of the booking. Yes
cancellationReason String One of either: (read more about cancellation reasons)

CANT_FULFILL_CUSTOMER_REQUEST
CHILD_SEAT_INCOMPATIBLE_VEHICLE
CHILD_SEAT_UNAVAILABLE
CHILD_SEAT_UNSUPPORTED
EXTRA_STOP
FORCE_MAJEURE
INCOMPLETE_BOOKING_DETAILS
INCORRECT_ADDRESS
LEAD_TIME_TOO_SHORT
MISSING_FLIGHT_NUMBER
NO_AVAILABILITY
RATE_ERROR
ROAD_CLOSURE
OTHER		 No

Sample Request

{
    "supplierResponse": "REJECT",
    "state_hash": "4b2c68f6c847284e73c73b26693d9905",
    "cancellationReason": "CANT_FULFILL_CUSTOMER_REQUEST"
}

HTTP 201 - Created

HTTP 400 - Bad Request

{
  "message": "Invalid Input Parameter",
  "description": "Invalid state_hash for booking status"
}

HTTP 401 - Unauthorized

{
  "message": "Invalid Authorization Token",
  "description": "Invalid authorization token in header"
}

HTTP 404 - Not Found

{
  "message": "Not Found",
  "description": "Booking Not Found"
}
Is this page helpful?    Yes   |    No