Event Availability Alert | Calendly | Developer Documentation

If you would like to notify event hosts when the availability of a given event type falls below a specified threshold, you can use the following APIs to gather the event types, their availability, and their hosts to send notifications.

Retrieve a list of all event types

Use GET https://api.calendly.com/event_types to get a collection of all your event types.

1 require 'faraday'
2 
3 token = '<your oauth token>'
4 user  = "https://api.calendly.com/users/<user_uuid>"
5 
6 params  = { user: user }
7 headers = {
8   'Content-Type'  => 'application/json',
9   'Authorization' => "Bearer #{token}"
10 }
11 
12 res = Faraday.get('https://api.calendly.com/event_types', params, headers)
13 
14 if res.status == 200
15   event_types    = JSON.parse(res.body)['collection']
16   scheduling_urls = event_types.map { |obj| obj['scheduling_url'] }
17 end

Example response (truncated):

1 {
2   "collection": [
3     {
4       ...
5       "uri": "http://api.calendly.com/event_types/88323028-5ef5-448b-9776-bc0c71b062a4",
6       "scheduling_url": "https://calendly.com/acmesales"
7       ...
8     }
9   ]
10 }

Filter the collection by event name:

1 specific_event_type = event_types.find { |obj| obj['name'] == 'my_event_name' }
2 scheduling_url = specific_event_type['scheduling_url']

Get available times for event

Use GET https://api.calendly.com/event_type_available_times, passing in the event type URI to get availability.

start_time and end_time are required parameters, must be in the future, and cannot span more than 31 days.

1 require 'faraday'
2 
3 token = '<your oauth token>'
4 low_availability_threshold = 3 # acceptable amount of available times
5 
6 params = {
7   event_type: event_type_uri, # chosen from previous API response
8   start_time:  '2024-02-16T24:00:00.000000Z',
9   end_time:    '2024-02-20T24:00:00.000000Z'
10 }
11 headers = {
12   'Content-Type'  => 'application/json',
13   'Authorization' => "Bearer #{token}"
14 }
15 
16 res = Faraday.get('http://api.calendly.com/event_type_available_times', params, headers)
17 
18 if res.status == 200
19   available_times    = JSON.parse(res.body)['collection']
20   availability_count = available_times.count
21 
22   if availability_count < low_availability_threshold
23     # send notification of low availability
24   end
25 end

Notify hosts

Use GET https://api.calendly.com/event_type_memberships to retrieve the host(s) of a given event type.

1 require 'faraday'
2 
3 token = '<your oauth token>'
4 
5 params  = { event_type: event_type_uri }
6 headers = {
7   'Content-Type'  => 'application/json',
8   'Authorization' => "Bearer #{token}"
9 }
10 
11 res = Faraday.get('https://api.calendly.com/event_type_memberships', params, headers)
12 
13 if res.status == 200
14   event_type_memberships = JSON.parse(res.body)['collection']
15   host_emails = event_type_memberships.map { |obj| obj['member']['email'] }
16 end

Example response (truncated):

1 {
2   "collection": [
3     {
4       ...
5       "member": {
6         "uri": "https://api.calendly.com/users/AAAAAAAAAAAAAAAA",
7         "name": "Tom Smith",
8         "email": "test@example.com"
9         ...
10       }
11       ...
12     }
13   ]
14 }