Skip to navigation

List Contacts

Returns a collection of Contacts.

Meeting date filters use the meeting dates recorded on each contact. Contacts with no recorded date for that field are not included.

Required scopes

contacts:read

Authentication

AuthorizationBearer
OAuth 2.0
OR
AuthorizationBearer
Personal Access Token

Query parameters

sortstringOptional

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.

emailstringOptional

Filter results by exact match on email address. Accepts a comma-separated list.

phone_numberstringOptional

Filter results by exact match on phone number. Accepts a comma-separated list.

timezonestringOptional

Filter results by exact match on the IANA time zone name(s). Accepts a comma-separated list of time zones.

min_last_meeting_datestringOptionalformat: "date-time"

Returns only contacts whose last recorded meeting date is on or after this date (inclusive). Use an ISO 8601 date-time in UTC. Calendly compares only the UTC date and ignores the time of day. For example, 2026-11-02T18:30:00Z returns the same contacts as 2026-11-02T00:00:00Z.

max_last_meeting_datestringOptionalformat: "date-time"

Returns only contacts whose last recorded meeting date is before this date (exclusive). Use an ISO 8601 date-time in UTC. Calendly compares only the UTC date and ignores the time of day. For example, 2026-11-03T18:30:00Z returns the same contacts as 2026-11-03T00:00:00Z. If this date is after the UTC date 30 days from today, Calendly uses that date as the exclusive bound.

min_next_meeting_datestringOptionalformat: "date-time"

Returns only contacts whose next recorded meeting date is on or after this date (inclusive). Use an ISO 8601 date-time in UTC. Calendly compares only the UTC date and ignores the time of day. For example, 2026-11-02T18:30:00Z returns the same contacts as 2026-11-02T00:00:00Z.

max_next_meeting_datestringOptionalformat: "date-time"

Returns only contacts whose next recorded meeting date is before this date (exclusive). Use an ISO 8601 date-time in UTC. Calendly compares only the UTC date and ignores the time of day. For example, 2026-11-03T18:30:00Z returns the same contacts as 2026-11-03T00:00:00Z. If this date is after the UTC date 30 days from today, Calendly uses that date as the exclusive bound.

namestringOptional

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_titlestringOptional

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).

companystringOptional

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).

countrystringOptional

Filter results by exact match on two-letter country code (ISO 3166-1 alpha-2). Accepts a comma-separated list.

statestringOptional

Filter results by exact match on state(s), province(s), or region(s). Accepts a comma-separated list of values.

citystringOptional

Filter results by exact match on city(ies). Accepts a comma-separated list of values.

contact_liststringOptionalformat: "uri"

Return only the contacts in this List or View (a contact list URI). For a dynamic_view, Calendly applies the View’s saved filters in the user’s time zone, as in the Calendly web app. If a View’s saved filters change after a page_token is issued, that page_token returns 400. Request the first page again. An unknown or hidden contact list returns 404.

countintegerOptional1-100Defaults to 20
The number of rows to return
page_tokenstringOptional
The token to pass to get the next or previous portion of the collection
excludestringOptional

Omit the listed fields from the response. Currently only custom_fields is supported. When omitted, all fields are returned.

Response

OK
collectionlist of objects
paginationobject

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error
500
Internal Server Error