All about Bookings

📘
Assumptions
In this working example we assume you have a proper username and password. We will refer from here as {username} and {password}.
Each time we have a parameter, for example the authentication token, we will write it with brackets. For example {example}.
All endpoints need a token to be authenticated.

🚧
Customer vs Lead Passenger
The customer is the travel agency making the booking, and the Lead Passenger is the one traveling. The customer's email will receive all notifications (creation, amendments, cancellations)

🚧
SMS Notification
The booking details are sent to the lead's mobile, along with service confirmation(s), 24 hours before each transfer.

🚧
Gold Protection
If the arrival transportation is cancelled, for whatever reason, you can call us at any time up until the scheduled departure time, and we will reschedule the affected transfer service at no extra cost (subject to availability) or provide a full refund. Without cancellation protection, the booking can only be rescheduled or canceled up to 48 hours before the transfer service.

List bookings

List all bookings filtered by date interval.

curl --location --request GET 'https://api.staging.suntransfers.biz/v1/bookings/{START_DATE}/{END_DATE}/{PAGE_INDEX}/{PAGE_LIMIT}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {TOKEN}'

{
    "references": [
        "SUNTR_XXXXX1",
        "SUNTR_XXXXX2",
        "SUNTR_XXXXX3"
    ]
}

Request explanation

Parameter	Type	Description
START_DATE	datetime	Start date time, for example 2020-01-01T00:00:00
END_DATE	datetime	End date time, for example 2020-12-31T23:59:59
PAGE_INDEX	integer	Page index, for example 1 the minimum page index is 1.
PAGE_LIMIT	integer	Page limit, for example 20 the maximum page limit is 100.

Response explanation

There is a response with a list of booking references.

Get booking

Get all the information about a booking by reference.

curl --location --request GET 'https://api.staging.suntransfers.biz/v1/bookings/{REFERENCE}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {TOKEN}'

{
    "reference": "SUNTR_XXXXX1",
    "status": "active",
    "lead_passenger": {
        "title": "Mrs",
        "name": "Butter",
        "surname": "Fly",
        "mobile": "+353 8546",
        "email": "[email protected]",
        "mobile_country": "18"
    },
    "customer": {
        "title": "Mrs",
        "name": "Butter",
        "surname": "Fly",
        "mobile": "+353 8546",
        "email": "[email protected]",
        "currency": "EUR"
    },
    "gold_protection": true,
    "sms_notification": true,
    "passengers": {
        "total": 3,
        "children_info": {
            "kids": 0,
            "babies": 0
        }
    },
    "currency": "EUR",
    "language": "1",
    "prices": {
        "payments": [
            {
                "currency": "EUR",
                "value": 283.54,
                "prefix_symbol": "",
                "suffix_symbol": "€"
            }
        ],
        "gold_protection": {
            "currency": "EUR",
            "value": 7.0,
            "prefix_symbol": "",
            "suffix_symbol": "€"
        },
        "sms_notification": {
            "currency": "EUR",
            "value": 3.0,
            "prefix_symbol": "",
            "suffix_symbol": "€"
        },
        "total": {
            "currency": "EUR",
            "value": 293.54,
            "prefix_symbol": "",
            "suffix_symbol": "€"
        }
    },
    "transfers": [
        {
            "outward": {
                "flight": {
                    "airline_code": "erty",
                    "flight_number": "ey",
                    "airport_code": "ert",
                    "flight_date_time": "2020-01-26 08:10:00",
                    "pickup_date_time": "2020-01-26 08:10:00"
                }
            },
            "destination": {
                "accommodation": {
                    "name": "2020-01-26T08:10:00+00:00",
                    "address": {
                        "name": "seg",
                        "address": "wert"
                    }
                }
            },
            "purchased_extra": [],
            "vehicle": {
                "id": 58,
                "code": "tx3",
                "type": "taxi",
                "title": "Private Taxi",
                "model": "",
                "description": "private",
                "max_passengers": 3,
                "max_luggage": 3,
                "is_shared": false
            },
            "route": {
                "id": 4099,
                "minutes": 165,
                "kilometers": 218
            }
        },
        {
            "outward": {
                "accommodation": {
                    "name": "2020-01-29T10:15:00+00:00",
                    "address": {
                        "name": "seg",
                        "address": "wert"
                    }
                }
            },
            "destination": {
                "flight": {
                    "airline_code": "ser",
                    "flight_number": "ertq",
                    "airport_code": "",
                    "flight_date_time": "2020-01-29 17:15:00",
                    "pickup_date_time": "2020-01-29 10:15:00"
                }
            },
            "purchased_extra": [],
            "vehicle": {
                "id": 58,
                "code": "tx3",
                "type": "taxi",
                "title": "Private Taxi",
                "model": "",
                "description": "private",
                "max_passengers": 3,
                "max_luggage": 3,
                "is_shared": false
            },
            "route": {
                "id": 4099,
                "minutes": 165,
                "kilometers": 218
            }
        }
    ]
}

Vehicle and Route object information you can see in All about Quotes

Request explanation

Parameter	Type	Description
REFERENCE	string	Is one of the references that we get from List bookings endpoint.

Response explanation

Field	Type	Description
reference	string	Booking reference
status	string	Booking status, could be ACTIVE, CANCELLED, PENDING. "ACTIVE": the booking is considered as ok. "CANCELLED": the booking was cancelled. "PENDING": if the agency is configured as "Point of Sale" (pay with credit card), the booking is waiting to be paid
lead_passenger	object	LeadPassenger object. Get the LeadPassenger information
customer	object	Customer object. Get the customer information
gold_protection	boolean	If booking has or not the Gold Protection service
sms_notification	boolean	If booking has or not the "Sms Notification" service
passengers	object	Passengers object. Get the passengers info
currency	string	Booking currency
language	string	Supplier language
prices	object	Prices object. Get the prices info
transfers	array object	Transfer object. Get the transfers info
essential_info	object	Get essential information.
priority_numbers	array object	Get the priority phone numbers
voucher	string	Link to Suntransfers voucher
external_ref	string	External reference, if is not provided in the create request, it should be empty

Prices object

Field	Type	Description
payments	array object	Price object. List of payments
gold_protection	object	Price object. Gold Protection price
sms_notification	object	Price object. Sms Notification price
total	object	Price object. Total amount

Transfer object.

Field	Type	Description
outward	object	Transfer object. Information about the outward
destination	object	Transfer object. Information about the destination
purchased_extra	array object	Transfer object. List of extras
vehicle	object	Transfer object. Description of the vehicle.
route	object	Transfer object. Information about the route
pickup_instructions	string	Transfer object. Pick-up instructions

Essential Info

Field	Type	Description
assistance	string	Information about assistance helplines
childseats	string	Information about child seats
luggage	string	Information about luggage
vehicle	string	Information about the vehicle
wait_time	string	Information about the wait time

Priority numbers object

Field	Type	Description
country	string	Phone country
phone	string	Phone

Create Booking

In order to be able to create a booking you need to previously have read the All About Quotes chapter.

To create a booking you need to save the "QUOTE_ID" of the quote which you prefer and the "OFFER_HASH" which you will find it at the bottom of the quote request response starting with "api_".

curl -X POST \
  https://api.staging.suntransfers.biz/v1/bookings \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {TOKEN}' \
  -d '{
    "quote_id": "{QUOTE_ID}",
    "offer": {
        "hash": "{OFFER_HASH}"
    },
    "customer": {
        "title": "Mr",
        "name": "John",
        "surname": "Doe",
        "email": "[email protected]",
        "mobile_country_code": "ES",
        "mobile_phone": "612345678"
    },
    "lead_passenger": {
        "title": "Mr",
        "name": "John",
        "surname": "Doe",
        "email": "[email protected]",
        "mobile_country_code": "ES",
        "mobile_phone": "612345678"
    },
    "gold_protection": true,
    "sms_notification": true,
    "passengers": {
        "total": 4,
        "children_info": [
            {
                "birthday": "2019-08-08"
            },
            {
                "birthday": "2019-01-01"
            }
        ]
    },
    "currency": "EUR",
    "language": "en",
    "transfers": [
        {
            "outward": {
                "flight": {
                    "airline_code": "LS",
                    "flight_number": "LS331",
                    "airport_code": "LHR",
                    "flight_date_time": "2019-12-22T11:35:00"
                }
            },
            "destination": {
                "accommodation": {
                    "name": "Hotel Wella",
                    "address": "addr, Maspalomas, 00173, ES",
                    "pickup_date_time": "2019-12-22T12:35:00"
                }
            },
            "purchased_extras": [
                {
                    "code": "golf_bag",
                    "quantity": 1
                }
            ]
        },
        {
            "outward": {
                "accommodation": {
                    "name": "Hotel Wella",
                    "address": "address, Maspalomas, 00173, ES",
                    "pickup_date_time": "2019-12-29T15:35:00"
                }
            },
            "destination": {
                "flight": {
                    "airline_code": "LS",
                    "flight_number": "LS332",
                    "airport_code": "LHR",
                    "flight_date_time": "2019-12-29T18:35:00"
                }
            },
            "purchased_extras": [
                {
                    "code": "golf_bag",
                    "quantity": 1
                }
            ]
        }
    ]
}'

{
    "reference": "SUNTR_XXXXXX",
    "price": {
        "currency": "EUR",
        "value": 70.8852,
        "prefix_symbol": "",
        "suffix_symbol": "€"
    },
    "price_eur": {
        "currency": "EUR",
        "value": 70.8852,
        "prefix_symbol": "",
        "suffix_symbol": "€"
    }
}

Request explanation

Field	Type	Description
quote_id	string	Mandatory field. The Quote Id that us get in the Quotes End Point
offer	object	Mandatory field. Offer object, set the hash that is get from Quotes End Point
customer	object	Mandatory field. Customer object, set the customer information
lead_passenger	object	Mandatory field. LeadPassenger object, set the LeadPassenger information
gold_protection	boolean	Mandatory field. Set if the customer want or not Gold Protection Service
sms_notification	boolean	Mandatory field. Set if the customer want or not SMS Notification
passengers	object	Mandatory field. Passengers object. Set the passengers info.
currency	string	Mandatory field. Set the currency that you want to use for the booking.
language	string	Mandatory field. Set the language for the booking.
transfers	object	Mandatory field. Set the transfer information
external_ref	string	Set a external reference

Offer object

Field	Type	Description
hash	string	Mandatory field. Set hash from Quotes End Point

Customer object

Field	Type	Description
title	string	Mandatory field. The title of the customer.
name	string	Mandatory field. The name of the customer.
surname	string	Mandatory field. The surname of the customer.
email	string	Mandatory field. The email of the customer.
mobile_country_code	string	Mandatory field. The country code of the customer, ex: ES
mobile_phone	string	Mandatory field. The phone number of the customer.

Lead Passenger object


title	string	Mandatory field. The title of the customer.
name	string	Mandatory field. The name of the customer.
surname	string	Mandatory field. The surname of the customer.
email	string	Mandatory field. The email of the customer.
mobile_country_code	string	Mandatory field. The country code of the customer, ex: ES
mobile_phone	string	Mandatory field. The phone number of the customer.

Passengers object

Field	Type	Description
total	integer	Mandatory field. The total number of passengers.
children_info	array object	Not Mandatory field. In case of no kids, you can skip this field.

Children Info object

Field	Type	Description
birthday	string	Mandatory field. Birthday of child.

Transfer object

Field	Type	Description
outward	object	Mandatory field.
destination	object	Mandatory field.
purchased_extras	object	Not Mandatory field.

Outward object

Only is necessary to set one of follow options

Field	Type	Description
flight	object	Flight information
accommodation	object	Accommodation information
cruise	object	Cruise information
train	object	Train information

Destination object

Only is necessary to set one of follow options

Field	Type	Description
flight	object	Flight information
accommodation	object	Accommodation information
cruise	object	Cruise information
train	object	Train information

Purchased Extras object

Field	Type	Description
code	string	Mandatory field. The code is get from Quotes End Point
quantity	integer	Mandatory field. The quantity of how many is want

Extras codes

Field	Type	Description
golf_bag	string	a bag full of golf sticks
skis	string	a device that allows you to lower snowy slopes
extra_bag	string	another bag
child_booster_seat	string	a booster seat
baby_seat	string	special seat for babies
wheelchair	string	a wheelchair
bicycle	string	a bicycle

Flight object

Field	Type	Description
airline_code	string	Mandatory field. Airline code
flight_number	string	Mandatory field. Flight number
airport_code	string	Mandatory field. Airport code (IATA). Is ignored in Amend
flight_date_time	string	Mandatory field for flight date based bookings or shared vehicle from accommodation to airport. Flight date time. Is ignored in Amend
pickup_date_time	string	Mandatory field for pick-up date based bookings. Pickup date time. Is ignored in Amend

Accommodation object

Field	Type	Description
name	string	Mandatory field for shuttles vehicles. Accommodation name
address	string	Mandatory field . Accommodation address
pickup_date_time	string	Mandatory field for pick-up date based bookings or outward object. Pickup date time. Is ignored in Amend
hotel_id	integer	Field for shuttles vehicles. Accommodation hotel id
google_place_id	string	Google place id

Cruise object

Field	Type	Description
cruise_line	string	Mandatory field. Cruise line
ship_name	string	Mandatory field. Ship name
cruise_terminal	string	Mandatory field. Cruise terminal
ship_date_time	string	Mandatory field for ship date based bookings or shared vehicle from accommodation to port station. Cruise date time. Is ignored in Amend
pickup_date_time	string	Mandatory field for pick-up date based bookings. Pickup date time. Is ignored in Amend

Train object

Field	Type	Description
train_number	string	Mandatory field. Train number
train_date_time	string	Mandatory field for train date based bookings or shared vehicle from accommodation to train station. Train date time. Is ignored in Amend
pickup_date_time	string	Mandatory field for pick-up date based bookings. Pickup date time. Is ignored in Amend

Response explanation

Field	Type	Description
reference	string	Booking reference
price	object	Price object, this is the price of request currency
price_eur	object	Price object, this is the price always in EUR currency
external_ref	string	External reference, if is not provided in the create request, it should be empty
transfers	array object	Transfers information

Price object

Field	Type	Description
currency	string	Code of currencies, for example: EUR, USD
value	float	The amount, for example: 123.45
prefix_symbol	string	If the symbol is in front of amount, for example $
suffix_symbol	string	If the symbol is at the end of the amount, for example €

Transfer object

Field	Type	Description
pickup_date_time	string	Pickup date and time for the transfer. Not available for shuttle transfers to the gateway at booking time
pickup_instructions	string	Pickup instructions for the transfer

Amend Booking

At the moment we only allow amending fields that don't change the initial price. Lead passenger details such as name, surname, phone, email are fields that don't impact at all the price.

Editing airline code and flight number won't affect the price either.
You are allowed to add or remove extras that are free of charge, ex: golf equipment.

The number of passengers can change as long as the number of seats of the car permits the change.

In case you edit a field that is not currently available for changing you will receive an error message.

curl -X PATCH \
  https://api.staging.suntransfers.biz/v1/bookings/SUNTR_XXXXXX \
  -H 'Authorization: Bearer {TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "lead_passenger": {
        "name": "Test",
        "surname": "Test",
        "mobile_country_code": "ES",
        "mobile_phone": "698765432",
        "email": "[email protected]"
    },
    "passengers": {
        "total": "2"
    },
    "transfers": [
        {
            "outward": {
                "flight": {
                    "airline_code": "LS",
                    "flight_number": "LS331"
                }
            },
            "destination": {
                "accommodation": {
                    "name": "Hotel Wella",
                    "address": "addr, Maspalomas1, 00173, ES"
                }
            },
            "purchased_extras": [
                {
                    "code": "child_booster_seat",
                    "quantity": 1
                }
            ]
        },
        {
            "outward": {
                "accommodation": {
                    "name": "Hotel Wella",
                    "address": "address, Maspalomas2, 00173, ES"
                }
            },
            "destination": {
                "flight": {
                    "airline_code": "LS",
                    "flight_number": "LS332"
                }
            },
            "purchased_extras": [
                {
                    "code": "child_booster_seat",
                    "quantity": 1
                }
            ]
        }
    ]
}'

Request explanation

Field	Type	Description
lead_passenger	object	Mandatory field. LeadPassenger object, set the LeadPassenger information
passengers	object	Mandatory field. Passengers object. Set the passengers info.
transfers	array object	Mandatory field. Set the transfer information

Cancel Booking

Bookings with Gold protection can be canceled at any time; on the other hand, those without it can only be canceled up to 48 hours before the transfer service.

curl -X DELETE \
  https://api.staging.suntransfers.biz/v1/bookings/SUNTR_XXXXXX \
  -H 'Authorization: Bearer {TOKEN}' \