> 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 Contacts GET https://api.calendly.com/contacts Returns a collection of Contacts > `contacts:read` Reference: https://developer.calendly.com/api-docs/calendly-api/contacts/list-contacts ## Authentication - `Authorization` header (bearer token, required) — OAuth 2.0 - `Authorization` header (bearer token, required) — Personal Access Token ## Request ### Query parameters - `sort` (string, optional) — Order results by the specified field and direction. Accepts comma-separated list of \{field}:\{direction} values. Supported fields are: created\_at, updated\_at. Sort direction is specified as: asc, desc. - `email` (string, optional) — Filter results by exact match on email address. Accepts a comma-separated list. - `phone_number` (string, optional) — Filter results by exact match on phone number. Accepts a comma-separated list. - `timezone` (string, optional) — Filter results by exact match on the IANA time zone name(s). Accepts a comma-separated list of time zones. - `name` (string, optional) — Filter results by partial match on name(s). Accepts a comma-separated list-- each segment is matched independently (commas in the query string separate values). - `job_title` (string, optional) — Filter results by partial match on job title(s). Accepts a comma-separated list-- each segment is matched independently (commas in the query string separate values). - `company` (string, optional) — Filter results by partial match on company name(s). Accepts a comma-separated list-- each segment is matched independently (commas in the query string separate values). - `country` (string, optional) — Filter results by exact match on two-letter country code (ISO 3166-1 alpha-2). Accepts a comma-separated list. - `state` (string, optional) — Filter results by exact match on state(s), province(s), or region(s). Accepts a comma-separated list of values. - `city` (string, optional) — Filter results by partial match on city(ies). Accepts a comma-separated list-- each segment is matched independently (commas in the query string separate values). - `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 - `exclude` (string, optional) — Omit the listed fields from the response. Currently only `custom_fields` is supported. When omitted, all fields are returned. ## Response ### 200 OK - `collection` (list of Contact, required) - `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-contactsRequestForbiddenError` ### 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) ### 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 ### Contact Information about a contact. - `uri` (string, required) — Canonical reference (unique identifier) for the contact. - `emails` (list of Email, required) — The user's email addresses. Max 10. - `created_at` (string, required) — The moment the user's record was created (e.g. "2026-01-15T18:01:09Z") - `updated_at` (string, required) — The moment the user's record was last updated (e.g. "2026-01-15T18:01:09Z") - `name` (string, optional, nullable) — The user's name (human-readable format). - `phone_numbers` (list of PhoneNumber, optional) — The user's phone numbers. Max 10. - `timezone` (string, optional, nullable) — The time zone to use when presenting time to the user. - `job_title` (string, optional, nullable) — The user's job title. - `company` (string, optional, nullable) — The user's company name. - `country` (string, optional, nullable) — The user's two letter country code. *(ISO 3166-1 alpha-2)* - `state` (string, optional, nullable) — The user's state, province, or region. - `city` (string, optional, nullable) — The user's city. - `linkedin` (string, optional, nullable) — The URL of the user's LinkedIn profile. - `custom_fields` (list of ContactCustomField, optional) — The contact's custom field values. - `first_email_date` (string, optional, nullable) — The timestamp of the earliest email exchanged with the contact. Always `null` immediately after a contact is created. - `last_email_date` (string, optional, nullable) — The timestamp of the most recent email exchanged with the contact. Always `null` immediately after a contact is created. - `next_meeting_date` (string, optional, nullable) — The timestamp of the next upcoming meeting scheduled with the contact. Always `null` immediately after a contact is created. - `last_meeting_date` (string, optional, nullable) — The timestamp of the most recent meeting held with the contact. Always `null` immediately after a contact is created. - `last_interaction_date` (string, optional, nullable) — The timestamp of the most recent interaction (email or meeting) with the contact. Always `null` immediately after a contact is created. ### 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) ### ContactsError Permission Denied - `title` (enum, required) - Allowed values: `Permission Denied` - `message` (enum, required) - Allowed values: `Please upgrade your Calendly account to Enterprise.`, `You do not have permission to access this resource.`, `Please upgrade to a paid Calendly account.`, `Contact creation is not available. Required features are not enabled for your account.` ### 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) ### Email An email address for a contact. Exactly one entry in the emails array must have is_primary true. - `email` (string, required) — Email address. - `is_primary` (boolean, required) — Whether this is the primary email. ### PhoneNumber A phone number associated with a contact. - `phone_number` (string, required) — Phone number. ### ContactCustomField A custom field value on a Contact. `uri` is the custom field definition URI. `label` is derived from the custom field definition's name. - `uri` (string, required) — Canonical URI of the custom field definition this value belongs to. - `value` (ContactCustomFieldValue, required, nullable) — The custom field value; the accepted type is set by the field definition's `field_type`. `text` and `single_select` take a string (`single_select` must equal one of the definition's option `uuid`s); `number` takes a number; `boolean` takes a boolean; `currency` takes an integer amount in the currency's minor units (the ISO currency code lives on the field definition, not on this entry); `date` takes a string in ISO 8601 date format (`YYYY-MM-DD`); `tags` takes an array of strings. Scalar fields reject array values, and `tags` rejects non-array values. - `label` (string, optional) — User-facing display name of the custom field (for readability). ### ContactCustomFieldValue The custom field value; the accepted type is set by the field definition's `field_type`. `text` and `single_select` take a string (`single_select` must equal one of the definition's option `uuid`s); `number` takes a number; `boolean` takes a boolean; `currency` takes an integer amount in the currency's minor units (the ISO currency code lives on the field definition, not on this entry); `date` takes a string in ISO 8601 date format (`YYYY-MM-DD`); `tags` takes an array of strings. Scalar fields reject array values, and `tags` rejects non-array values. ## Examples **Response** ```json { "collection": [ { "uri": "https://api.calendly.com/contacts/CCCCCCCCCCCCCCCC", "emails": [ { "email": "test@example.com", "is_primary": true } ], "created_at": "2026-01-15T18:01:09Z", "updated_at": "2026-01-15T18:01:09Z", "name": "Jane Doe", "phone_numbers": [ { "phone_number": "+1 888-888-8888" } ], "timezone": "America/Los_Angeles", "job_title": "Director of Operations", "company": "ExampleCo", "country": "US", "state": "CA", "city": "San Francisco", "linkedin": "https://www.linkedin.com/in/janedoe", "custom_fields": [ { "uri": "https://api.calendly.com/contacts/custom_field_definitions/CCCCCCCCCCCCCCCC", "value": "event", "label": "Lead source" } ], "first_email_date": "2026-01-08T11:00:00.000Z", "last_email_date": "2026-01-08T11:00:00.000Z", "next_meeting_date": "2026-01-08T11:00:00.000Z", "last_meeting_date": "2026-01-08T11:00:00.000Z", "last_interaction_date": "2026-01-08T11:00:00.000Z" } ], "pagination": { "count": 20, "next_page": "https://api.calendly.com/event_types?count=1&page_token=sNjq4TvMDfUHEl7zHRR0k0E1PCEJWvdi", "previous_page": "https://api.calendly.com/event_types?count=1&page_token=VJs2rfDYeY8ahZpq0QI1O114LJkNjd7H", "next_page_token": "sNjq4TvMDfUHEl7zHRR0k0E1PCEJWvdi", "previous_page_token": "VJs2rfDYeY8ahZpq0QI1O114LJkNjd7H" } } ``` **SDK Code** ```python import requests url = "https://api.calendly.com/contacts" querystring = {"city":"San Francisco, Buffalo","company":"Company Name, Another Company","country":"US","email":"contact_email@example.com, another-email@example.com","exclude":"custom_fields","job_title":"Account Executive, CEO","name":"Jane Doe, John Smith","phone_number":"+1 888-888-8888, +1 777-777-7777","sort":"created_at:asc","state":"NY, CA","timezone":"America/Los_Angeles, America/New_York"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.calendly.com/contacts?city=San+Francisco%2C+Buffalo&company=Company+Name%2C+Another+Company&country=US&email=contact_email%40example.com%2C+another-email%40example.com&exclude=custom_fields&job_title=Account+Executive%2C+CEO&name=Jane+Doe%2C+John+Smith&phone_number=%2B1+888-888-8888%2C+%2B1+777-777-7777&sort=created_at%3Aasc&state=NY%2C+CA&timezone=America%2FLos_Angeles%2C+America%2FNew_York'; 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 package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.calendly.com/contacts?city=San+Francisco%2C+Buffalo&company=Company+Name%2C+Another+Company&country=US&email=contact_email%40example.com%2C+another-email%40example.com&exclude=custom_fields&job_title=Account+Executive%2C+CEO&name=Jane+Doe%2C+John+Smith&phone_number=%2B1+888-888-8888%2C+%2B1+777-777-7777&sort=created_at%3Aasc&state=NY%2C+CA&timezone=America%2FLos_Angeles%2C+America%2FNew_York" 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 require 'uri' require 'net/http' url = URI("https://api.calendly.com/contacts?city=San+Francisco%2C+Buffalo&company=Company+Name%2C+Another+Company&country=US&email=contact_email%40example.com%2C+another-email%40example.com&exclude=custom_fields&job_title=Account+Executive%2C+CEO&name=Jane+Doe%2C+John+Smith&phone_number=%2B1+888-888-8888%2C+%2B1+777-777-7777&sort=created_at%3Aasc&state=NY%2C+CA&timezone=America%2FLos_Angeles%2C+America%2FNew_York") 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 import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.calendly.com/contacts?city=San+Francisco%2C+Buffalo&company=Company+Name%2C+Another+Company&country=US&email=contact_email%40example.com%2C+another-email%40example.com&exclude=custom_fields&job_title=Account+Executive%2C+CEO&name=Jane+Doe%2C+John+Smith&phone_number=%2B1+888-888-8888%2C+%2B1+777-777-7777&sort=created_at%3Aasc&state=NY%2C+CA&timezone=America%2FLos_Angeles%2C+America%2FNew_York") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.calendly.com/contacts?city=San+Francisco%2C+Buffalo&company=Company+Name%2C+Another+Company&country=US&email=contact_email%40example.com%2C+another-email%40example.com&exclude=custom_fields&job_title=Account+Executive%2C+CEO&name=Jane+Doe%2C+John+Smith&phone_number=%2B1+888-888-8888%2C+%2B1+777-777-7777&sort=created_at%3Aasc&state=NY%2C+CA&timezone=America%2FLos_Angeles%2C+America%2FNew_York', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.calendly.com/contacts?city=San+Francisco%2C+Buffalo&company=Company+Name%2C+Another+Company&country=US&email=contact_email%40example.com%2C+another-email%40example.com&exclude=custom_fields&job_title=Account+Executive%2C+CEO&name=Jane+Doe%2C+John+Smith&phone_number=%2B1+888-888-8888%2C+%2B1+777-777-7777&sort=created_at%3Aasc&state=NY%2C+CA&timezone=America%2FLos_Angeles%2C+America%2FNew_York"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.calendly.com/contacts?city=San+Francisco%2C+Buffalo&company=Company+Name%2C+Another+Company&country=US&email=contact_email%40example.com%2C+another-email%40example.com&exclude=custom_fields&job_title=Account+Executive%2C+CEO&name=Jane+Doe%2C+John+Smith&phone_number=%2B1+888-888-8888%2C+%2B1+777-777-7777&sort=created_at%3Aasc&state=NY%2C+CA&timezone=America%2FLos_Angeles%2C+America%2FNew_York")! 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() ```