> Calendly developer docs. For page Markdown, append .md to any URL.
> Index: https://developer.calendly.com/llms.txt
> API catalog: https://developer.calendly.com/.well-known/api-catalog
> OpenAPI: https://developer.calendly.com/openapi/calendly-api.yaml
> OAuth authorization server: https://calendly.com/.well-known/oauth-authorization-server
> MCP protected resource: https://mcp.calendly.com/.well-known/oauth-protected-resource
> Scheduling MCP endpoint: https://mcp.calendly.com
> Docs search MCP: https://developer.calendly.com/_mcp/server

# Event Availability Alert

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.

```ruby
require 'faraday'

token = '<your oauth token>'
user  = "https://api.calendly.com/users/<user_uuid>"

params  = { user: user }
headers = {
  'Content-Type'  => 'application/json',
  'Authorization' => "Bearer #{token}"
}

res = Faraday.get('https://api.calendly.com/event_types', params, headers)

if res.status == 200
  event_types    = JSON.parse(res.body)['collection']
  scheduling_urls = event_types.map { |obj| obj['scheduling_url'] }
end
```

Example response (truncated):

```json
{
  "collection": [
    {
      ...
      "uri": "http://api.calendly.com/event_types/88323028-5ef5-448b-9776-bc0c71b062a4",
      "scheduling_url": "https://calendly.com/acmesales"
      ...
    }
  ]
}
```

Filter the collection by event name:

```ruby
specific_event_type = event_types.find { |obj| obj['name'] == 'my_event_name' }
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.

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

```ruby
require 'faraday'

token = '<your oauth token>'
low_availability_threshold = 3 # acceptable amount of available times

params = {
  event_type: event_type_uri, # chosen from previous API response
  start_time:  '2024-02-16T24:00:00.000000Z',
  end_time:    '2024-02-20T24:00:00.000000Z'
}
headers = {
  'Content-Type'  => 'application/json',
  'Authorization' => "Bearer #{token}"
}

res = Faraday.get('http://api.calendly.com/event_type_available_times', params, headers)

if res.status == 200
  available_times    = JSON.parse(res.body)['collection']
  availability_count = available_times.count

  if availability_count < low_availability_threshold
    # send notification of low availability
  end
end
```

## Notify hosts

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

```ruby
require 'faraday'

token = '<your oauth token>'

params  = { event_type: event_type_uri }
headers = {
  'Content-Type'  => 'application/json',
  'Authorization' => "Bearer #{token}"
}

res = Faraday.get('https://api.calendly.com/event_type_memberships', params, headers)

if res.status == 200
  event_type_memberships = JSON.parse(res.body)['collection']
  host_emails = event_type_memberships.map { |obj| obj['member']['email'] }
end
```

Example response (truncated):

```json
{
  "collection": [
    {
      ...
      "member": {
        "uri": "https://api.calendly.com/users/AAAAAAAAAAAAAAAA",
        "name": "Tom Smith",
        "email": "test@example.com"
        ...
      }
      ...
    }
  ]
}
```