List Contacts | Calendly | Developer Documentation

const url = 'https://api.calendly.com/contacts';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

{
  "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"
  }
}

Returns a collection of Contacts

Required scopes

contacts:read

Returns a collection of Contacts <Info title="Required scopes"> > `contacts:read` </Info>

Authentication

AuthorizationBearer

OAuth 2.0

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.

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 partial match on city(ies). Accepts a comma-separated list— each segment is matched independently (commas in the query string separate values).

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

collectionlist of objects

paginationobject

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error