> 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 # List Shares GET https://api.calendly.com/shares Returns the user's Shares, newest first. Use it to find a Share created in an earlier session, for example to update or delete it. The list matches the user's Single-use links tab in the My Calendly view: user-managed Shares on Event Types the user owns or hosts, including one-off meetings. Like the tab, it leaves out disabled Shares, Shares created from meeting polls, and links booked through instant booking. > `shares:read` Reference: https://developer.calendly.com/api-docs/calendly-api/shares/list-shares ## Authentication - `Authorization` header (bearer token, required) — OAuth 2.0 - `Authorization` header (bearer token, required) — Personal Access Token ## Request ### Query parameters - `user` (string, required) — The URI of the user whose Shares should be returned. Must be the authenticated user. Another user returns 403. - `min_created_at` (string, optional) — Only Shares created at or after this time. ISO 8601, UTC. - `max_created_at` (string, optional) — Only Shares created before this time. ISO 8601, UTC. - `event_type` (string, optional) — The URI of the Event Type. Return only Shares created from this Event Type. If the Event Type does not exist, the collection is empty. - `sort` (enum, optional, default: created_at:desc) — Order results by creation time. Supported values: `created_at:desc` (default), `created_at:asc`. - Allowed values: `created_at:desc`, `created_at:asc` - `count` (integer, optional, default: 20) — The number of rows to return - `page_token` (string, optional) — The token to pass to get the next or previous portion of the collection ## Response ### 200 OK - `collection` (list of Share, required) — The set of shares matching the criteria - `pagination` (Pagination, required) ## Errors ### 400 Bad Request Error Request is not valid - `title` (enum, required) - Allowed values: `Internal Server Error` - `message` (enum, required) - Allowed values: `The server encountered an unexpected condition that prevented it from fulfilling the request.` - `details` (list of ErrorResponseDetailsItem, optional) ### 401 Unauthorized Error Cannot authenticate caller - `title` (enum, required) - Allowed values: `Internal Server Error` - `message` (enum, required) - Allowed values: `The server encountered an unexpected condition that prevented it from fulfilling the request.` - `details` (list of ErrorResponseDetailsItem, optional) ### 403 Forbidden Error Permission denied or insufficient scope - `List-sharesRequestForbiddenError` - ListSharesRequestForbiddenError0 - InsufficientScopeError: InsufficientScopeError ### 404 Not Found Error Requested resource not found - `title` (enum, required) - Allowed values: `Internal Server Error` - `message` (enum, required) - Allowed values: `The server encountered an unexpected condition that prevented it from fulfilling the request.` - `details` (list of ErrorResponseDetailsItem, optional) ### 429 Too Many Requests Error Too Many Requests - `title` (enum, required) - Allowed values: `Internal Server Error` - `message` (enum, required) - Allowed values: `The server encountered an unexpected condition that prevented it from fulfilling the request.` - `details` (list of ErrorResponseDetailsItem, optional) ### 500 Internal Server Error An error has occurred on the server - `title` (enum, required) - Allowed values: `Internal Server Error` - `message` (enum, required) - Allowed values: `The server encountered an unexpected condition that prevented it from fulfilling the request.` - `details` (list of ErrorResponseDetailsItem, optional) ## Types ### Share - `uri` (string, required) — The canonical URI of the share. - `contact` (string, required, nullable) — The URI of the contact that the share is for. `null` if the share has no contact. - `created_at` (string, required) — The time at which the share was created. - `status` (enum, required) — The status of the share: - `active`: invitees can book with the share. - `booked`: an invitee booked with the share. - `expired`: the share expired without a booking. - Allowed values: `active`, `booked`, `expired` - `scheduling_links` (list of ShareSchedulingLinksItems, required) — The scheduling links for the share. The array is empty when the share has no scheduling link. - `share_override` (ShareShareOverride, required) — The effective scheduling settings for bookings with this share. Each field is the value that applies when an invitee books. When the share does not override a setting, the value is the parent Event Type value. ### Pagination - `count` (integer, required) — The number of rows to return - `next_page` (string, required, nullable) — URI to return the next page of an ordered list ("null" indicates no additional results are available) - `previous_page` (string, required, nullable) — URI to return the previous page of an ordered list ("null" indicates no additional results are available) - `next_page_token` (string, required, nullable) — Token to return the next page of an ordered list ("null" indicates no additional results are available) - `previous_page_token` (string, required, nullable) — Token to return the previous page of an ordered list ("null" indicates no additional results are available) ### ErrorResponseDetailsItem - `message` (string, required) - `parameter` (string, optional) - `code` (string, optional) ### ListSharesRequestForbiddenError0 Error Object - `title` (enum, required) - Allowed values: `Permission Denied` - `message` (enum, required) - Allowed values: `You do not have permission to access this resource.`, `You do not have permission` - `details` (list of ErrorResponseDetailsItem, optional) ### InsufficientScopeError Caller does not have required oauth scopes - `title` (enum, required) - Allowed values: `Insufficient scope` - `message` (enum, required) - Allowed values: `This operation requires the scopes listed in the 'required_scopes' array.` - `required_scopes` (list of string, required) ### ShareSchedulingLinksItems - `booking_url` (string, required) — Scheduling link url - `owner` (string, optional) — A link to the resource that owns this Scheduling Link (currently, this is always an Event Type) - `owner_type` (enum, optional) — Resource type (currently, this is always EventType) - Allowed values: `EventType` ### ShareShareOverride The effective scheduling settings for bookings with this share. Each field is the value that applies when an invitee books. When the share does not override a setting, the value is the parent Event Type value. - `name` (string, optional) — The event name that invitees see. - `duration` (integer, optional) — The default event duration, in minutes. - `duration_options` (list of integer, optional) — The event durations, in minutes, that invitees can select. The array is empty when the share does not offer multiple durations. - `period_type` (enum, optional) — How the date range for bookings is calculated: - `fixed`: invitees can book only between `start_date` and `end_date`. - `moving`: invitees can book within a rolling window. Use `max_booking_time` to set the length of the window in minutes. Every calendar day counts toward the window. - `available_moving`: invitees can book within a rolling window. Use `max_booking_time` to set the length of the window in minutes. Only Monday through Friday count toward the window; weekends are excluded. - `unlimited`: invitees can book with no date range limit. - Allowed values: `available_moving`, `moving`, `fixed`, `unlimited` - `start_date` (string, optional, nullable) — The first date that invitees can book when `period_type` is `fixed`. Format: `YYYY-MM-DD` `null` when `period_type` is not `fixed`. - `end_date` (string, optional, nullable) — The last date that invitees can book when `period_type` is `fixed`. Format: `YYYY-MM-DD` `null` when `period_type` is not `fixed`. - `max_booking_time` (integer, optional, nullable) — How far in the future invitees can book, in minutes. Applies when `period_type` is `moving` or `available_moving`. `null` when the effective booking window has no rolling limit. - `min_booking_time` (integer, optional, nullable) — The minimum notice that invitees must give before the start of an event, in seconds. `null` when no minimum notice is configured. - `hide_location` (boolean, optional, nullable) — Whether the location is hidden until the invitee books. This setting applies only when the share has one custom location. When the share does not override this setting, the value is the Event Type value. - `location_configurations` (list of ShareShareOverrideLocationConfigurationsItems, optional) — The meeting locations for the share. The array is empty when no custom locations apply to the share. - `availability_rule` (ShareShareOverrideAvailabilityRule, optional) — The effective availability rules for the share, including rules from the parent Event Type when the share does not define its own. ### ShareShareOverrideLocationConfigurationsItems - `location` (string, optional, nullable) — The location value. Returned for `physical`, `custom`, and `ask_invitee` locations when a value is set. - `additional_info` (string, optional, nullable) — More information about the location. Returned for `physical` and `inbound_call` locations when a value is set. - `phone_number` (string, optional, nullable) — The phone number that invitees call. Returned for `inbound_call` locations. - `position` (integer, optional) — The sort order of this location in the list. - `kind` (enum, optional) — The type of location: - `physical`: an in-person location. - `ask_invitee`: the invitee provides the location. - `custom`: a custom location label. - `outbound_call`: the host calls the invitee. - `inbound_call`: the invitee calls the host. - `google_conference`: Google Meet. - `gotomeeting_conference`: GoTo Meeting. - `microsoft_teams_conference`: Microsoft Teams. - `zoom_conference`: Zoom. - Allowed values: `physical`, `ask_invitee`, `custom`, `outbound_call`, `inbound_call`, `google_conference`, `gotomeeting_conference`, `microsoft_teams_conference`, `zoom_conference` ### ShareShareOverrideAvailabilityRule The effective availability rules for the share, including rules from the parent Event Type when the share does not define its own. - `rules` (list of ShareShareOverrideAvailabilityRuleRulesItems, required) — The availability rules. - `timezone` (string, required) — The time zone of the availability rules. ### ShareShareOverrideAvailabilityRuleRulesItems - `type` (enum, required) — The rule type. A `wday` rule applies to a day of the week. A `date` rule applies to one date. - Allowed values: `wday`, `date` - `intervals` (list of ShareShareOverrideAvailabilityRuleRulesItemsIntervalsItems, required) — The time ranges when invitees can book. An empty array means that no times are available. - `wday` (enum, optional) — The day of the week. Returned for `wday` rules. - Allowed values: `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday` - `date` (string, optional) — The date. Returned for `date` rules. Format: `YYYY-MM-DD` ### ShareShareOverrideAvailabilityRuleRulesItemsIntervalsItems - `from` (string, required) — The start of the time range. Format: `"hh:mm"` - `to` (string, required) — The end of the time range. Format: `"hh:mm"` ## Examples **Response** ```json { "collection": [ { "uri": "https://api.calendly.com/shares/AAAAAAAAAAAAAAAA", "contact": "https://api.calendly.com/contacts/CCCCCCCCCCCCCCCC", "created_at": "2019-01-02T03:04:05.678123Z", "status": "active", "scheduling_links": [ { "booking_url": "https://calendly.com/d/abcd-brv8/30-minute-meeting", "owner": "https://api.calendly.com/event_types/BBBBBBBBBBBBBBBB", "owner_type": "EventType" } ], "share_override": { "name": "30 Minute Meeting", "duration": 30, "duration_options": [ 30 ], "period_type": "fixed", "start_date": "2026-10-08", "end_date": "2026-10-08", "max_booking_time": null, "min_booking_time": null, "hide_location": false, "location_configurations": [], "availability_rule": { "rules": [ { "type": "wday", "intervals": [ { "from": "19:00", "to": "20:00" } ], "wday": "thursday" } ], "timezone": "America/Los_Angeles" } } } ], "pagination": { "count": 1, "next_page": null, "previous_page": null, "next_page_token": null, "previous_page_token": null } } ``` **SDK Code** ```python Shares import requests url = "https://api.calendly.com/shares" querystring = {"event_type":"https://api.calendly.com/event_types/BBBBBBBBBBBBBBBB","max_created_at":"2019-08-07T06:05:04.321123Z","min_created_at":"2019-01-02T03:04:05.678123Z","sort":"created_at:desc","user":"https://api.calendly.com/users/AAAAAAAAAAAAAAAA"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript Shares const url = 'https://api.calendly.com/shares?event_type=https%3A%2F%2Fapi.calendly.com%2Fevent_types%2FBBBBBBBBBBBBBBBB&max_created_at=2019-08-07T06%3A05%3A04.321123Z&min_created_at=2019-01-02T03%3A04%3A05.678123Z&sort=created_at%3Adesc&user=https%3A%2F%2Fapi.calendly.com%2Fusers%2FAAAAAAAAAAAAAAAA'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Shares package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.calendly.com/shares?event_type=https%3A%2F%2Fapi.calendly.com%2Fevent_types%2FBBBBBBBBBBBBBBBB&max_created_at=2019-08-07T06%3A05%3A04.321123Z&min_created_at=2019-01-02T03%3A04%3A05.678123Z&sort=created_at%3Adesc&user=https%3A%2F%2Fapi.calendly.com%2Fusers%2FAAAAAAAAAAAAAAAA" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Shares require 'uri' require 'net/http' url = URI("https://api.calendly.com/shares?event_type=https%3A%2F%2Fapi.calendly.com%2Fevent_types%2FBBBBBBBBBBBBBBBB&max_created_at=2019-08-07T06%3A05%3A04.321123Z&min_created_at=2019-01-02T03%3A04%3A05.678123Z&sort=created_at%3Adesc&user=https%3A%2F%2Fapi.calendly.com%2Fusers%2FAAAAAAAAAAAAAAAA") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java Shares import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.calendly.com/shares?event_type=https%3A%2F%2Fapi.calendly.com%2Fevent_types%2FBBBBBBBBBBBBBBBB&max_created_at=2019-08-07T06%3A05%3A04.321123Z&min_created_at=2019-01-02T03%3A04%3A05.678123Z&sort=created_at%3Adesc&user=https%3A%2F%2Fapi.calendly.com%2Fusers%2FAAAAAAAAAAAAAAAA") .header("Authorization", "Bearer ") .asString(); ``` ```php Shares request('GET', 'https://api.calendly.com/shares?event_type=https%3A%2F%2Fapi.calendly.com%2Fevent_types%2FBBBBBBBBBBBBBBBB&max_created_at=2019-08-07T06%3A05%3A04.321123Z&min_created_at=2019-01-02T03%3A04%3A05.678123Z&sort=created_at%3Adesc&user=https%3A%2F%2Fapi.calendly.com%2Fusers%2FAAAAAAAAAAAAAAAA', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp Shares using RestSharp; var client = new RestClient("https://api.calendly.com/shares?event_type=https%3A%2F%2Fapi.calendly.com%2Fevent_types%2FBBBBBBBBBBBBBBBB&max_created_at=2019-08-07T06%3A05%3A04.321123Z&min_created_at=2019-01-02T03%3A04%3A05.678123Z&sort=created_at%3Adesc&user=https%3A%2F%2Fapi.calendly.com%2Fusers%2FAAAAAAAAAAAAAAAA"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift Shares import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.calendly.com/shares?event_type=https%3A%2F%2Fapi.calendly.com%2Fevent_types%2FBBBBBBBBBBBBBBBB&max_created_at=2019-08-07T06%3A05%3A04.321123Z&min_created_at=2019-01-02T03%3A04%3A05.678123Z&sort=created_at%3Adesc&user=https%3A%2F%2Fapi.calendly.com%2Fusers%2FAAAAAAAAAAAAAAAA")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```