# Overview Power your travel search or booking platform with the best ground transportation inventory in the United States. Seamlessly add ground transfers search and booking to your travel site or platform. ### Requests The Found Hero API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support [cross-origin resource sharing](http://en.wikipedia.org/wiki/Cross-origin_resource_sharing), allowing you to interact securely with our API from a client-side web application (though you should never expose your secret access token in any public website's client-side code).. For the production environment, all requests should use the following base URL: ```bash https://api.shuttlefare.com ``` If you are using the Shulltefare within the sandbox environment, use the following base URL: ```bash http://sandbox-api.shuttlefare.com ``` ### Authentication For all of the resources in our API, you will also be required to have a valid Shuttlefare API key.You need to send it as a header, called API-KEY. If the API key is required and is not provided, the API will return a HTTP 403 response. {% hint style="info" %} Always include **API-KEY: \** Header in your requests {% endhint %} ### Error Handling For most of the API responses, errors will probably come in 2 major categories: authentication errors (**HTTP 403**), most likely due to missing or invalid API key, and bad requests errors (**HTTP 400**) due to malformed inputs.
# Workflow Currently we offer 3 steps to book a service with Shuttlefare as indicated below: 1. [**Get fare quotes**](/integration-flow/searching) 2. [**Book Reservation**](/integration-flow/booking) 3. [**Cancel**](/integration-flow/cancellation) [**Reservation**](/integration-flow/cancellation) {% hint style="warning" %} **The Order is important** In order to book a reservation you always need to do searching first and find a convenient rate to proceed within the booking operation. {% endhint %} # Get Fare Quotes Get Fare Quotes allows you to provide basic details describing the needed ride, for example, the start and end locations (e.g. LAX Airport to Hilton Checkers Hotel in Los Angeles, flight arrival or departure times (e.g. 13:00, 3:30), the number of passengers and either one-way or round-trip. Next, you are returned an array of service providers and fare quotes, each quote will have all data describing the offered service (e.g. the service provider offering the service, the type of vehicle, any restrictions that may apply (maximum number of passengers and bags allowed, gratuity included, car seats offered etc.), and total price for all passengers. {% hint style="warning" %} **You need a rate for each reservation you made** You can pick one rate from the searching result and use it once to book a reservation. You can't use the same rate for booking another reservation. {% endhint %} # Book Reservation The next step involves the user selecting a service provider and associated vehicle and rate. Additionally to data from the rate, you will be required to pass all contact details from the passengers: names, email addresses, phone number and flight data (if relevant). Passengers are also able to send special instructions to providers, if supported by them (e.g. “Sign with name” or “Please call me to get access to my apartment complex”). After a reservation is placed successfully, our API will return the reservation information along with a confirmation id that may be used for further requests (for example: cancellations ). {% hint style="info" %} **\_id** field is the id that you will be using to refer to the reservation. You may use that id to cancel the reservation for example {% endhint %} # Cancel Reservation This process allows you to request for a cancellation if within the cancellation policy guidelines. Our API requires the **\_id** of the reservation and reason of cancellation to proceed with a cancellation.
# Search ### Highlights: * To describe a location you need to specify the zip code along with the address. For an airport, send the airports’ IATA code (e.g. JFK), and for other types of locations please try to provide as much data as you can. * Please provide the `pickup_date` *& `pickup_time`* when possible. If you cannot and your search is to or from an airport, you may use `flight_date` & *`flight_time`* and our API will calculate an estimated pickup time for it. * If you need to perform a round-trip search (mode = round\_trip), don’t forget to provide either `return_flight_date` and `return_flight_time` ## Search for rate `GET` `https://api.shuttlefare.com/api/rates` This endpoint allows you to get rates list #### Query Parameters | Name | Type | Description | | ------------ | ------ | ------------------------------------------ | | trip\_type | string | one\_way or round\_trip | | flight\_time | string | flight time. examples: "15:30" | | flight\_date | string | flight date must be in format: yyyy-mm-dd | | address | string | Full address | | zip\_code | string | zip code of the address | | airport | string | airport code. example: JFK | | pickup\_type | string | T OR F ( T : to airport or from airport) | | passengers | number | number of passengers. example: 2 | | api | string | both OR pc OR ridenfly | {% tabs %} {% tab title="200 " %} ``` [ { "id": "pc-3998124-10", "api": "pc", "name": "SUV", "TripTotalAmount": "99.35", "image_url": "https://www.privatecarapp.com/uploads/car_images/10.jpg", "bookable": true, "cancellation": { "amendable": true, "cancellable_offline": true, "cancellable_online": true, "policy": [ { "notice": 48, "refund_percent": 100 } ] }, "max_bags": 4, "max_passengers": 11, "gratuity_accepted": true, "gratuity_included": false, "amendable": true, "currency_info": { "code": "USD", "prefix_symbol": "$", "suffix_symbol": "" } }, { "id": "ridenfly-7070", "api": "ridenfly", "name": "Shared Shuttle Van", "TripTotalAmount": "77.58", "image_url": "http://prod.ridenfly.net/system/companies/images/000/000/120/original/logo7.png?1584809747", "bookable": true, "cancellation": { "amendable": true, "cancellable_offline": true, "cancellable_online": true, "policy": [ { "notice": 48, "refund_percent": 100 } ] }, "max_bags": 4, "max_passengers": 11, "gratuity_accepted": true, "gratuity_included": false, "amendable": true, "currency_info": { "code": "USD", "prefix_symbol": "$", "suffix_symbol": "" } } ] ``` {% endtab %} {% tab title="400 Missing inputs" %} ``` { message: "passengers is required"} ``` {% endtab %} {% tab title="403 Unauthorized !" %} ``` { message: "Please provide an access token in the request"} ``` {% endtab %} {% endtabs %} # Book You can book/cancel reservations here ## Book Reservation `POST` `https://api.shuttlefare.com/api/reservations` To book a reservation you select rate and service provider. #### Request Body | Name | Type | Description | | ------------------- | ------ | ------------------------------------------------ | | flight\_number | string | The flight number | | airline | string | The airline IATA code of the flight | | gratuity | number | | | pickup\_type | string | T or F ( T is to Airport. F is from the airport) | | zip\_code | string | zip code of the address | | address | string | Location address | | airport | string | airport code. Example: JFK | | num\_of\_passengers | number | number of passengers | | email | string | email of the person booking | | phone | string | phone number of the person booking | | last\_name | string | Last name of the person booking | | first\_name | string | First name of the person booking | | pickup\_time | string | pickup time. Example: "09:00" | | pickup\_date | string | pickup date must be in format : yyyy-mm-dd | | rate\_id | string | Rate id that you get from GET rates endpoint | {% tabs %} {% tab title="200 Reservation successfully booked." %} ``` { "canceled": false, "cancellation_reason": "", "_id": "608ec0fb781fa89ba984eaaa", "reservation_id": "32930", "createdAt": "2021-05-02T15:10:51.664Z", "updatedAt": "2021-05-08T23:55:52.343Z", "TripTotalAmount": "80.74", "address": "85207, 310 North 86th Street, Mesa, AZ, USA, Mesa, AZ 85207", "airport": "PHX", "api": "pc", "email": "test@tester.com", "first_name": "Aimad", "gratuity": 10, "last_name": "String", "num_of_passengers": 2, "phone": "05737371", "pickup_date": "2021-05-24", "pickup_time": "08:35", "pickup_type": "LA", "rate_id": "pc-3961948-8", "zip_code": "85207" } ``` {% endtab %} {% endtabs %} ## Get All Reservations `GET` `https://api.shuttlefare.com/api/reservations` You can get a list of all reservations {% tabs %} {% tab title="200 " %} ``` [ { "canceled": false, "cancellation_reason": "", "_id": "608ec0fb781fa89ba984eaaa", "reservation_id": "32930", "createdAt": "2021-05-02T15:10:51.664Z", "updatedAt": "2021-05-08T23:55:52.343Z", "TripTotalAmount": "80.74", "address": "85207, 310 North 86th Street, Mesa, AZ, USA, Mesa, AZ 85207", "airport": "PHX", "api": "pc", "email": "test@tester.com", "first_name": "Aimad", "gratuity": 10, "last_name": "String", "num_of_passengers": 2, "phone": "05737371", "pickup_date": "2021-05-24", "pickup_time": "08:35", "pickup_type": "LA", "rate_id": "pc-3961948-8", "zip_code": "85207" }, { "canceled": false, "cancellation_reason": "", "_id": "608ec1ae781fa89ba984eb18", "reservation_id": "29991", "address": "85207, 310 North 86th Street, Mesa, AZ, USA, Mesa, AZ 85207", "api": "ridenfly", "createdAt": "2021-05-02T15:13:50.240Z", "email": "test@tester.com", "first_name": "Aimad", "gratuity": 10, "last_name": "String", "num_of_passengers": 2, "phone": "05737371", "pickup_date": "2021-05-24", "pickup_time": "08:35", "rate_id": "ridenfly-7070", "updatedAt": "2021-05-02T15:13:50.240Z", "zip_code": "85207" }, { "canceled": false, "cancellation_reason": "", "_id": "608ec293781fa89ba984eb4d", "reservation_id": "29992", "address": "85207, 310 North 86th Street, Mesa, AZ, USA, Mesa, AZ 85207", "api": "ridenfly", "createdAt": "2021-05-02T15:17:39.470Z", "email": "test@tester.com", "first_name": "Aimad", "gratuity": 10, "last_name": "String", "num_of_passengers": 2, "phone": "05737371", "pickup_date": "2021-05-24", "pickup_time": "08:35", "rate_id": "ridenfly-7070", "updatedAt": "2021-05-02T15:17:39.470Z", "zip_code": "85207" }, { "canceled": false, "cancellation_reason": "", "_id": "608fe129781fa89ba984ee15", "reservation_id": "30010", "address": "85207, 310 North 86th Street, Mesa, AZ, USA, Mesa, AZ 85207", "api": "ridenfly", "createdAt": "2021-05-03T11:40:25.155Z", "email": "test@tester.com", "first_name": "Aimad", "gratuity": 10, "last_name": "String", "num_of_passengers": 2, "phone": "05737371", "pickup_date": "2021-05-24", "pickup_time": "08:35", "rate_id": "ridenfly-7070", "updatedAt": "2021-05-03T11:40:25.155Z", "zip_code": "85207" }, { "canceled": false, "cancellation_reason": "", "_id": "60971ae8f367f84fc49a718e", "reservation_id": "30172", "address": "85207, 310 North 86th Street, Mesa, AZ, USA, Mesa, AZ 85207", "airport": "PHX", "api": "ridenfly", "createdAt": "2021-05-08T23:12:40.078Z", "email": "test@tester.com", "first_name": "Aimad", "gratuity": 10, "last_name": "String", "num_of_passengers": 2, "phone": "05737371", "pickup_date": "2021-05-24", "pickup_time": "08:35", "pickup_type": "LA", "rate_id": "ridenfly-7070", "updatedAt": "2021-05-08T23:12:40.078Z", "zip_code": "85207" }, { "canceled": false, "cancellation_reason": "", "_id": "60971b54f367f84fc49a71af", "reservation_id": "30173", "TripTotalAmount": "77.58", "address": "85207, 310 North 86th Street, Mesa, AZ, USA, Mesa, AZ 85207", "airport": "PHX", "api": "ridenfly", "createdAt": "2021-05-08T23:14:28.747Z", "email": "test@tester.com", "first_name": "Aimad", "gratuity": 10, "last_name": "String", "num_of_passengers": 2, "phone": "05737371", "pickup_date": "2021-05-24", "pickup_time": "08:35", "pickup_type": "LA", "rate_id": "ridenfly-7070", "updatedAt": "2021-05-08T23:14:28.747Z", "zip_code": "85207" } ] ``` {% endtab %} {% endtabs %} # Cancel {% hint style="info" %} **Cancellation Policy** rates have a cancellation policy describing whether the trip is cancellable or not, and how many hours of notice are given to be entitled to a 100% refund. {% endhint %} {% hint style="danger" %} **Operation cannot be undone** Keep in mind that this operation cannot be undone and that refunds may take up to 5 business days to be issued by our payments processor. {% endhint %} ## Cancel Reservation `POST` `https://api.shuttlefare.com/api/reservations/cancel` This endpoint allows you to cancel a confirmed reservation. #### Request Body | Name | Type | Description | | -------------------- | ------ | ---------------------------------------------------------------------------------------------- | | id | string | `_id` of reservation you want to cancel ( make sure you're sending `_id` Not `reservation_id`) | | cancellation\_reason | string | | {% tabs %} {% tab title="200 Cake successfully retrieved." %} ``` { "message": "Reservation cancelled successfully!"} ``` {% endtab %} {% endtabs %}