Who's this integration guide for.
This integration guide is designed for the developers of booking, brokerage, aggregator and discovery platforms that would like to get live availability, confirm bookings and sync data back to integrated management systems.
Developers of property management systems should contact us for integration information.
The integration is broken down into steps and is designed to help drastically reduce integration time and development resources.
Before getting started.
If not completed yet, refer to docs on syncing data to get started and confirm your platform meets the base setup requirements with these use-cases:
- An existing user is able to securely connect to your platform from Syncaroo.
- An existing user is then able to map & connect their locations as needed from their management software to your platform.
- Your platform is able to receive webhook updates from Syncaroo.
- Your platform is authenticated and able to fetch live data updates via the Syncaroo API.
Current API endpoints
Dig into Syncaroo’s Unified API Endpoints here.
Setting up Availability, Bookings & 2-way Syncs
Availability & Booking Data for Resources / Inventory
Using our /v1/locations/{ID}/resources/{ID}/availability endpoint, you are able to request up to 3 months of availability per resource.
You can pass ?start=Y-m-d&end=Y-m-d if you want specific time ranges, otherwise, you will receive 90 days of data after today.
This ‘cache’ will allow for faster search on your end.
Primary Actions to Complete & Recommendations
- Using your existing connection to our API, retrieve and store availability for the time frame you allow searching in your platform using the endpoint above.
This data is separated by start and end datetime values to be easy to store for each day. - At the beginning of each day, add the new availability data for the day at the end of your time range. (Example below). Do this by searching availability with a time range parameter like the following for the additional day you need
GET /v1/locations/{ID}/resources/{ID}/availability?start=2021-12-08&end=2021-12-08
Example
- Let’s say you wanted 30 days of availability data for 1 or many inventory items like a meeting room.
- Query the availability endpoint similar to the following: /v1/locations/{ID}/resources/{ID}/availability?start=2021-12-01&end=2021-12-31
- When a new day arrives, you will want the data for January 1st, 2022. That way you still have your 30 days of data in the future that you want.
- As a result, query /v1/locations/{ID}/resources/{ID}/availability?start=2021-01-01&end=2021-01-01
- This way, you only need to add or update smaller pieces of data which reduces the load on your system and is much faster to process.
Notifications of Availability Changes
When bookings are made within the inventory system we will notify you of changes to the availability via a webhook.
Note: With Phase 1 complete, you will not need to do anything new to receive this webhook.
Primary Actions to Complete & Recommendations
Once the webhook is received with a change, parse the recurrence portion of the webhook:
"recurrence": {
"seriesStart": "2021-12-08T18:00:00.000Z",
"seriesEnd" : "2021-12-08T18:30:00.000Z",
"rRule" : null
},
- if recurrence->rRule is not null, then pull a completely new cache for the resource
- If recurrence->rRule is null, then refresh only the day(s) that the booking is made on. Add the start and end dates to the availability search similar to the above and replace that data in your cache.
Confirm Booking with 2-way Sync
Once a customer is ready to make a booking (2 way syncing), do the following:
Primary Actions to Complete & Recommendations
- Begin your typical process of booking on your end.
- Once you are ready to make the booking in the Operator’s system, send the booking details to us to confirm.
- Use our /v1/webhooks endpoint for the request
- We will either complete the booking with the operator or return an error if unsuccessful. If successful, your booking will now be added to the operator’s system.
- We will then respond with a success message and a booking reference in case you would need to modify or delete the booking in the future
Example
Let’s say that Jane would like to make a booking on your platform for 10:00 to 11:00 AM tomorrow.
When that user clicks to book, they complete the requirements on your end.
After these requirements have been completed such as adding a valid CC, filling in certain details, etc, send a notification(webhook) to our webhooks endpoint with the booking details.
Syncaroo will then go through all the processes of confirming whether the booking can be made or not. If the booking time frame is possible, we will make the booking and pass the booking details back to your platform immediately.
