List suggested contacts
curl --request GET \
--url https://api.cal.com/v2/contacts/suggestions \
--header 'Authorization: <authorization>'import requests
url = "https://api.cal.com/v2/contacts/suggestions"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://api.cal.com/v2/contacts/suggestions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cal.com/v2/contacts/suggestions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.cal.com/v2/contacts/suggestions"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.cal.com/v2/contacts/suggestions")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cal.com/v2/contacts/suggestions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"status": "success",
"data": [
{
"email": "jamie.rivera@example.com",
"name": "Jamie Rivera",
"meetingCount": 6,
"lastMetAt": "2026-10-02T09:30:00.000Z"
}
],
"pagination": {
"nextCursor": "<string>",
"hasMore": true
}
}Contacts
List suggested contacts
Returns people the authenticated user keeps meeting but hasn’t added as personal contacts: attendees of at least 4 accepted, past bookings the user hosted in the last 12 months. Existing contacts, the user’s own emails, dismissed suggestions and blocked emails are left out. Ordered by meeting count, then most recent meeting, with limit/cursor pagination; when pagination.hasMore is true, pass pagination.nextCursor as cursor. To accept a suggestion, add it with POST /v2/contacts using its email and name. To hide it for good, dismiss it with POST /v2/contacts/suggestions/dismissals. If accessed using an OAuth access token, the CONTACT_READ scope is required.
GET
/
v2
/
contacts
/
suggestions
List suggested contacts
curl --request GET \
--url https://api.cal.com/v2/contacts/suggestions \
--header 'Authorization: <authorization>'import requests
url = "https://api.cal.com/v2/contacts/suggestions"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://api.cal.com/v2/contacts/suggestions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cal.com/v2/contacts/suggestions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.cal.com/v2/contacts/suggestions"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.cal.com/v2/contacts/suggestions")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cal.com/v2/contacts/suggestions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"status": "success",
"data": [
{
"email": "jamie.rivera@example.com",
"name": "Jamie Rivera",
"meetingCount": 6,
"lastMetAt": "2026-10-02T09:30:00.000Z"
}
],
"pagination": {
"nextCursor": "<string>",
"hasMore": true
}
}Headers
Query Parameters
Was this page helpful?