References¶

Testing Booking Management¶

There are 24 test bookings available, cached for 1 hour. When calling GET /v1/bookings, not all 24 may be returned because CANCELLED and COMPLETE status bookings are filtered out (mirroring production behaviour). You can retrieve these via GET /v1/bookings/:customerReference/:bookingReference.

After 1 hour, test bookings are refreshed. You can filter results by status and pickup date, just like in production.

See the Booking Management section for endpoint details.

Testing Driver Management/Tracking¶

Once a booking has been accepted, you can test driver management and tracking:

Create a driver (if using Booking.com Driver App) or provide driver details directly during assignment
Assign a driver — booking transitions to DRIVER_ASSIGNED
Send driver events in sequential order:

DRIVER_DEPARTED_TO_PICKUP
→ DRIVER_ARRIVED_AT_PICKUP
→ DRIVER_DEPARTED_TO_DROPOFF
→ DRIVER_ARRIVED_AT_DROPOFF

You may also send DRIVER_LIVE_LOCATION updates with GPS coordinates between events.

For customer no-show scenarios, send DRIVER_SUBMITTED_CUSTOMER_NO_SHOW after DRIVER_ARRIVED_AT_PICKUP.

See the Driver Management section for endpoint details.

Testing Rates Search¶

The search webhook validation endpoint tests your implementation by triggering a search against your system and running automated validation checks.

Note

The sandbox validation endpoint path is /v2/searchResults (camelCase). In production, the path is /v2/search-results (kebab-case).

Search webhook validation¶

POST /v2/searchResults

You can either leave the body empty (uses pre-determined search parameters) or provide your own search parameters to test specific locations/scenarios.

Request Headers¶

These headers are mandatory:

Header	Description	Example
Oauth-Client-Id	Your OAuth client ID (generated by you)	example-client-id
Oauth-Client-Secret	Your OAuth client secret (generated by you)	example-client-secret
Supplier-URL	Base URL for your OAuth and search endpoints (HTTPS)	https://your-api.com

Payload Fields¶

Optionally provide search parameters to test against a specific location. See the Search Webhook References for the full payload field specification.

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, 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¶

Parameter	Type	Description
oauthStatusCode	Integer	HTTP status code from your OAuth token endpoint.
oauthValidationErrors	Array	Validation errors in your OAuth response (empty if successful).
searchResultStatusCode	Integer	HTTP status code from your search endpoint. Note: a 200 does not mean results are usable — check validation errors.
searchResultValidationErrors	Array	List of validation errors in your search response (e.g. missing fields, invalid enum values).
searchResults	Array	The response received from your search endpoint.
errorMessage	String	Any errors encountered when performing the validation (e.g. connection timeout).

Sample Response — Success¶

{
   "oauthStatusCode": 200,
   "oauthValidationErrors": [],
   "searchResultStatusCode": 200,
   "searchResultValidationErrors": [],
   "searchResults": [
       {
           "searchResultId": "c4c7c90b-a6bf-451a-a3e5-90fed6a9c8d3",
           "transportCategory": "STANDARD",
           "price": {
               "salePriceMin": 8.81,
               "salePriceMax": 8.81,
               "currency": "USD"
           },
           "minPassengers": 1,
           "maxPassengers": 3,
           "provider": {
               "name": "Local Taxi (Robot Fleet US)",
               "phoneNumber": "+12014810000"
           },
           "features": [
               {
                   "name": "noOfBags",
                   "value": "1"
               }
           ],
           "genius": {
                "benefitType": "PERCENTAGE",
                "percentageDiscount": 5
           }
       }
   ]
}

Sample Response — Validation Failures¶

{
   "oauthStatusCode": 200,
   "searchResultStatusCode": 200,
   "searchResultValidationErrors": [
       "results[1].minPassengers: must not be null",
       "results[0].searchResultId: must not be null",
       "results[0].transportCategory: PEOPLECARRIE is not a valid enum value",
       "results[0].genius.percentageDiscount: must be between 5 and 10"
   ],
   "searchResults": [
       {
           "searchResultId": null,
           "transportCategory": "PEOPLECARRIE",
           "price": {
               "salePriceMin": 64.27,
               "salePriceMax": 64.27,
               "currency": "EUR"
           }
       }
   ]
}

Sample Response — Connection Error¶

{
   "oauthStatusCode": null,
   "searchResultStatusCode": null,
   "errorMessage": "Connection timed out"
}