Skip to content

References

Receiving searches

To receive searches and provide rates via our webhooks, you need to implement the following:

POST /v2/search-results

Payload Fields

Warning

The pickup_date_time given in the search request and booking retrieval can differ. This is due to flight number details being added post search. The information given in the booking retrieval should be used.

The payload contains origin and destination objects, each with the following location fields:

Parameter Type Description
origin.latitude Number The origin latitude. Always present.
origin.longitude Number The origin longitude. Always present.
origin.name String The full address of the origin location. Always present.
origin.city String|null The origin city. May not be available for all requests.
origin.country String The origin country (ISO 3166 alpha-2). Always present.
origin.postcode String|null The origin postcode. May not be available for all requests.
origin.iata String|null The origin IATA code. Only populated for airport locations.
destination.latitude Number The destination latitude. Always present.
destination.longitude Number The destination longitude. Always present.
destination.name String The full address of the destination location. Always present.
destination.city String|null The destination city. May not be available for all requests.
destination.country String The destination country (ISO 3166 alpha-2). Always present.
destination.postcode String|null The destination postcode. May not be available for all requests.
destination.iata String|null The destination IATA code. Only populated for airport locations.
passengers Integer The number of passengers travelling.
pickupDateTime Datetime The pickup timestamp in UTC (ISO 8601).
pickupTimezone String The pickup timezone in IANA format.
drivingDistanceInKm Float|null The distance between the origin & destination locations. May not be available for all requests.
genius.level One of the following values:

GENIUS_ONE
GENIUS_TWO
GENIUS_THREE
NON_GENIUS		 The Genius level of the customer.

Note

Use latitude and longitude to calculate rates. Address parts (name, city, country, postcode) are provided for additional context but should not be the primary input for rate calculation.

Sample Payload

{
    "origin": {
        "latitude": 48.8735513,
        "longitude": 2.3426615,
        "name": "29 Rue du Faubourg Montmartre, 75009 Paris, France",
        "city": "Paris",
        "country": "FR",
        "postcode": "75009",
        "iata": null
    },
    "destination": {
        "latitude": 48.8564826,
        "longitude": 2.3524135,
        "name": "Hotel de Ville, FR, Place de l'Hôtel de Ville, 75004 Paris, France",
        "city": "Paris",
        "country": "FR",
        "postcode": "75004",
        "iata": null
    },
    "passengers": 1,
    "pickupDateTime": "2020-10-23T12:00:00Z",
    "pickupTimezone": "Europe/Paris",
    "drivingDistanceInKm": 3.51,
    "genius": {
        "level": "GENIUS_ONE"
    }
}

Response Fields

Your response must contain a results array with one entry per vehicle category you wish to offer pricing for.

Field Type Description Required
searchResultId String A unique identifier for this search result. Maximum length: 100 characters. Yes
transportCategory String One of the following values:

STANDARD
LUXURY
EXECUTIVE
PEOPLE_CARRIER
LARGE_PEOPLE_CARRIER
EXECUTIVE_PEOPLE_CARRIER
MINIBUS
ELECTRIC_STANDARD
ELECTRIC_LUXURY		 Yes
price.salePriceMin Float The minimum sale price. Where there is no min/max range, both values should be the same. Yes
price.salePriceMax Float The maximum sale price. Where there is no min/max range, both values should be the same. Yes
price.currency String The currency of the price, in ISO 4217 format. Should match your vendor currency. Yes
minPassengers Integer The minimum number of passengers the vehicle will accommodate. Yes
maxPassengers Integer The maximum number of passengers the vehicle will accommodate. Yes
features Array The features of the vehicle. Possible values are:

noOfBags — indicating the number of bags the vehicle will accommodate.		 No
servicesAvailable Array An array of available services. Possible value: meetAndGreet. Do not return this for non-airport pickups. No
provider.name String The name of the end supplier. Required if you are not the end-supplier (i.e. you are a marketplace). Limited to 255 characters. No
provider.phoneNumber String The phone number of the end supplier, in E.164 format. Required for marketplaces. No
genius Object The Genius discount details. If no Genius discount is offered, omit this field or set to null. No
genius.benefitType One of the following values:

PERCENTAGE		 The type of Genius discount. Must not be null if genius object is provided. No
genius.percentageDiscount Integer The percentage of Genius discount. Minimum: 5, maximum: 10. Must not be null if genius object is provided. No

Sample Response Body

{
    "results": [
        {
            "searchResultId": "88394930355",
            "transportCategory": "STANDARD",
            "price": {
                "salePriceMin": 44.29,
                "salePriceMax": 44.29,
                "currency": "EUR"
            },
            "minPassengers": 1,
            "maxPassengers": 3,
            "features": [
                {
                    "name": "noOfBags",
                    "value": "3"
                }
            ],
            "servicesAvailable": [
                "meetAndGreet"
            ],
            "provider": {
                "name": "Company name 1",
                "phoneNumber": "+49 30 346 494 367"
            },
            "genius": {
                "benefitType": "PERCENTAGE",
                "percentageDiscount": 5
            }
        },
        {
            "searchResultId": "88359",
            "transportCategory": "EXECUTIVE",
            "price": {
                "salePriceMin": 221.23,
                "salePriceMax": 221.23,
                "currency": "EUR"
            },
            "minPassengers": 1,
            "maxPassengers": 4,
            "features": [
                {
                    "name": "noOfBags",
                    "value": "3"
                }
            ],
            "servicesAvailable": [
                "meetAndGreet"
            ],
            "provider": {
                "name": "Company Name 2",
                "phoneNumber": "+49 30 346 494 367"
            },
            "genius": null
        }
    ]
}

Responses

HTTP 200 - OK

HTTP 4xx - Client error — Error response format

HTTP 5xx - Server error — Error response format

Further reading