Bulk fetching of Bookings objects via API

nitish_springboard · December 21, 2021, 12:19pm

Bulk Fetch of Bookings from API:
In one of our use cases, we need to fetch all bookings for a call type from YCBM datastore within a time window and sync our platform Database. The issue we are facing is that, the total number of bookings that we need to fetch from YCBM datastore are large in number. The number of network calls that our platform needs to make are large in number because Bookings fetch API only returns 10 booking objects in a single API call . This task therefore is taking too much time due to the large number of network calls we have to make in order to retrieve all Booking objects.

Is there any way to Bulk fetch Booking objects ?

Ben · December 21, 2021, 1:41pm

@nitish_springboard welcome to the Forum! There isn’t a way to do a bulk GET for booking data. We use the pagination process to prevent a large drain on resources. As you have mentioned there can be a significant amount of bookings, breaking them up to a more manageable slice keeps things from being overloaded. With that said I will have a catch up with the engineering team on options here.

vaibhav.singh · July 8, 2022, 10:16am

Hey @Ben , I’m stuck at this step… how can load all my Bookings and events into my database. Can anyone please help me here.
Also @nitish_springboard … If u have done that… I would be happy to connect with you.
Thanks

Ben · July 14, 2022, 7:56pm

@vaibhav.singh when running a GET you will need to paginate through the bookings either forward or backward. Inside of the returned header you will see a link to move things in the direction. And this is based off of the booking start date and time. You also have the ability to run an export of your bookings to then get a CSV of the data to import into a database or business intelligent tool: View, manage and export your booking activity - YouCanBook.me Support

Beyond this you could also setup a webhook to pass the booking data from our system to another system. Right now there is not a way to authenticate the webhook, but in the near future we will allow for a header to be added. More info here: Passing data to other systems - YouCanBook.me Support

nitish_springboard · October 16, 2023, 1:38pm

hey @Ben , any update on above request:
1. Bulk Fetch of Bookings from API:
In one of our use cases, we need to fetch all bookings for a call type from YCBM datastore within a time window and sync our platform Database. The issue we are facing is that, the total number of bookings that we need to fetch from YCBM datastore are large in number. The number of network calls that our platform needs to make are large in number because Bookings fetch API only returns 10 booking objects in a single API call . This task therefore is taking too much time due to the large number of network calls we have to make in order to retrieve all Booking objects.

Is there any way to Bulk fetch Booking objects ?

Ben · October 17, 2023, 4:12pm

@nitish_springboard at this time there is not a way to bulk fetch bookings through the API. The best alternative is to run an export from within the app as I linked to above. We are working on a v2 of our API and having bulk functionality is up for consideration.

kl3603 · April 2, 2025, 5:49pm

Hi @Ben, any updates on bulk fetch bookings through the API?

Ben · April 2, 2025, 6:26pm

@kl3603 This is now possible with our bookings query end point.

https://api.youcanbook.me/v1/accounts/{accountId}/bookings/query

For the fields you could add:

?searchTimeRangeCriteria=createdAt&pageSize=500&from=2025-03-01T00:00:00Z

This will give you up to 500 bookings per page, and in the returned header you will have a direction to go either forward or backward according to the search criteria. I will work on getting this information added to our API documentation. Let me know if you have any questions.

kl3603 · April 2, 2025, 7:41pm

@Ben, Thank you very much Ben, I was able to import my bookings. Do you have a list of the possible fields for selection?

Ben · April 2, 2025, 8:36pm

Request Parameters:

accountId (PathVariable) required
● Type: String
● Description: Unique identifier for the account.

bookingPageIds (RequestParam)
● Type: Array of Strings
● Description: List of booking page identifiers, if not present, all booking
pages will be included in the response.

statuses (RequestParam)
● Type: Array of Strings
● Description: List of booking statuses that should be included in the
response
● Valid values: tentative, rejected, cancelled, upcoming, inProgress, finished
and noShow

fromBookingId (RequestParam)
● Type: String
● Description: Starting booking id considered in the sort operation

from (RequestParam) required
● Type: Date
● Description: Start date (ISO) of the time range.
● Format (yyyy-MM-dd’T’HH:mm:ss.SSSXXZ) eg. 2010-12-01T00:00:00Z

to (RequestParam)
● Type: Date
● Description: End date (ISO) of the time range.
● Format (yyyy-MM-dd’T’HH:mm:ss.SSSXXZ) eg. 2010-12-01T00:00:00Z

searchTextCriteria (RequestParam)
● Type: Array of Strings
● Description: List of booking fields to be compared with the provided
searchText
● Valid values: title, form, ref

searchTimeRangeCriteria (RequestParam)
● Type: String
● Description: Field should be used to filter a time range with parameters
from and to.
● Default value: startsAt
● Valid values: startsAt, createdAt

searchText (RequestParam)
● Type: String
● Description: Text to be compared with the parameter searchTextCriteria

direction (RequestParam)
● Type: String
● Default Value: forwards
● Description: Pagination direction.
● Valid values: forwards, backwards

sortBy (RequestParam)
● Type: String
● Default Value: startsAt
● Description: Sorting criteria for the booking list.
● Valid values: startsAt, createdAt

pageSize (RequestParam)
● Type: Integer
● Default Value: 50
● Description: Number of bookings per page.
● Valid values: Any integer between 10 and 500

mikezianb · April 8, 2025, 6:14am

Hi Ben,

I’m getting weird results when filtering bookings by searchTimeRangeCriteria=createdAt

Here’s the filter criteria

/bookings?searchTimeRangeCriteria=createdAt&sortBy=createdAt&pageSize=200&from=2025-04-01T00:00:00Z&fields=createdAt,startsAt,endsAt

JSON response
{
“createdAt” : “2025-03-28T16:54:12Z”,
“endsAt” : “2025-04-03T09:30:00”,
“startsAt” : “2025-04-03T09:00:00”
},
{
“createdAt” : “2025-03-31T00:40:51Z”,
“endsAt” : “2025-04-03T08:30:00”,
“startsAt” : “2025-04-03T08:00:00”
},
{
“createdAt” : “2025-04-01T03:55:19Z”,
“endsAt” : “2025-04-03T11:00:00”,
“startsAt” : “2025-04-03T10:30:00”
},
{
“createdAt” : “2025-04-02T13:36:19Z”,
“endsAt” : “2025-04-03T10:30:00”,
“startsAt” : “2025-04-03T10:00:00”
}

…

What could be the issue on my filter that is seems it didn’t exclude bookings created before 2025-04-01T00:00:00Z?

I specifically set the filter by:
searchTimeRangeCriteria=createdAt
&sortBy=createdAt
&from=2025-04-01T00:00:00Z
&pageSize=200

Ben · April 9, 2025, 12:43pm

We have two end points for retrieving bookings the older one which is /bookings, and the newer one which is /bookings/query.

Try this out:
{accountId}/bookings/query?searchTimeRangeCriteria=createdAt&sortBy=createdAt&pageSize=200&from=2025-04-01T00:00:00Z

The /bookings won’t have all of the added filtering and search functionality. While that endpoint does allow for field control &fields=x,y,z, it will only return 10 bookings per request compared to up to 500 with the query endpoint. If you need to paginate on either endpoint there will be a link returned in the header to go forward or backward in time.

mikezianb · April 10, 2025, 4:12am

I’m getting Internal Server Error from the response
{
“code” : “ycbm_api_unknown_error”,
“errors” : ,
“httpCode” : 500,
“httpStatusCode” : 500,
“message” : “Unexpected error”,
“status” : “INTERNAL_SERVER_ERROR”,
“type” : “YcbmApiException”
}

What could be the issue from this call?

{account_id}/bookings/query?searchTimeRangeCriteria=createdAt&sortBy=createdAt&pageSize=200&from=2025-04-01T00:00:00Z

Ben · April 10, 2025, 4:08pm

You are using the full URL while authenticating (AccountId and API key)?
https://api.youcanbook.me/v1/accounts/{account_id}/bookings/query?searchTimeRangeCriteria=createdAt&sortBy=createdAt&pageSize=200&from=2025-04-01T00:00:00Z

Swap out {account_id} with your AccountId

mikezianb · April 10, 2025, 5:01pm

Yes I’m using my AccountId

Ben · April 11, 2025, 3:15pm

@mikezianb it could be something with the authorization. I am going to send you a direct message so I can get your account id and check on things.

mikezianb · April 11, 2025, 7:18pm

How can I see the DM from the forum interface?

Topic		Replies	Views
Bulk Fetching Bookings objects via API API	3	96	April 11, 2025
How can I get all booking API	1	974	June 7, 2021
The basics of basics! query an appointment? API	1	50	October 27, 2025
Retrieving All Bookings without Pagination API	1	57	July 8, 2025
Unable to retrieve all current and future booking using bookings endpoint	1	36	December 9, 2025

Bulk fetching of Bookings objects via API

Related topics