1. Keys & Testing (Onboarding)
Q: How do I obtain API Keys? A: You can obtain your keys by opening a support ticket or by contacting your Account Manager. We provide both Sandbox and Production keys simultaneously so you can begin development immediately.
Q: When can I perform testing in the Sandbox? A: Sandbox testing is active during UK business hours (06:00 to 18:00 UK time).
Q: What can I actually test in Sandbox?
V1 Flow: You can test the complete lifecycle from
NEWstatus to driver assignment and subsequent events.V2 Search: This is used to test your authentication and mapping. These use mockup bookings that are not specific to your inventory.
Resetting: Asking for a new token will return all sandbox settings to their original state.
2. Booking Management & Flow
Q: What is the state_hash and how do I handle it? A: The state_hash is a version control ID. If a POST returns a 400 Bad Request, your hash is stale. You must call GET /v1/bookings/ to fetch the latest hash before retrying your request.
Q: Should I automate booking rejections? A: We strongly advise against this. Rejecting a booking is treated as a "Decline" and impacts your performance metrics. We suggest rejections be a separate manual check within your system rather than automated logic.
Q: How do we stay in sync with Booking.com? A: To avoid asynchronous data issues, your team should use your own internal system rather than the Booking.com portal as much as possible. This ensures your local database remains the "source of truth."
Q: Do we receive notifications for all cancellations? A: No. For declined bookings, you will not receive a cancellation notification via the V2 webhook. You must consistently check the status via GET /v1/bookings.
3. Driver Events & GPS
Q: How do I assign a driver and do I need a Driver ID? A: Use the V2 Assignment endpoint. You do not need to register a Driver ID beforehand. Because you are using your own driver app, you simply provide the driver’s info and vehicle details directly during the assignment call.
Q: What are the requirements for Live Location (GPS)? A: Once a driver is "on the way," we require GPS updates every 5 to 15 seconds. High-frequency updates are essential for the customer experience.
Q: Are Driver IDs needed for events? A: No. Since you are using your own driver application, Driver IDs are not required when sending driver events.
4. Webhooks (Self-Service)
Q: How do I register my webhook endpoints? A: Registration is a self-service process. You only need to register one Base URL for all webhook endpoints.
Search Webhook: Active by default (requires a support ticket or contact with your Account Manager only for creating API locations).
Booking & Incident Webhooks: These require Self-Enrolment.
Q: Is the V2 Booking Webhook sufficient for all data? A: No. The V2 webhook is a notification-only trigger and does not carry the full booking payload. When you receive it, you must call the V1 booking endpoint to retrieve the full details.
Q: What does "Fire and Forget" mean for webhooks? A: Webhooks are "fire and forget," meaning the system sends the notification once and will not attempt to resend it if your server is down or the delivery fails. Because there is no retry logic, you must use periodic polling of the V1 endpoint as a safety net.
Q: Can I disable webhooks later? A: Yes. You can disable them at any time via self-service with no impact on your existing reservation API flows.
5. Meeting Points & Pickup Instructions
Q: What information is required for pickups? A: Specificity is essential, especially for airports. You must provide:
Pickup Type: (e.g., Meet & Greet, Host, Desk, or Curbside).
Specific Details: All info is essential. For airport pickups, provide specific instructions per booking to ensure a smooth connection between driver and passenger.
Still have questions?
For a detailed technical breakdown of each endpoint and its features, please refer to our API Documentation. You can also explore our full library of integration guides and best practices in our Help Center Articles.