curl --request GET \
--url https://api.cal.id/contacts/ \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.cal.id/contacts/"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.cal.id/contacts/', 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.id/contacts/",
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: Bearer <token>"
],
]);
$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.id/contacts/"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
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.id/contacts/")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cal.id/contacts/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"rows": [
{
"id": 3041,
"name": "Priya Sharma",
"email": "priya.sharma@example.com",
"phone": "+44 20 7946 0102",
"metadata": {
"company": "Northwind Ltd",
"source": "website"
},
"notes": "Met at the London meetup.",
"createdAt": "2026-02-18T12:41:09.000Z",
"updatedAt": "2026-04-22T14:05:33.000Z",
"lastMeetingAt": "2026-04-22T14:00:00.000Z"
},
{
"id": 3042,
"name": "Sam Okafor",
"email": "sam.okafor@example.com",
"phone": "+234 1 271 0000",
"metadata": {
"company": "Northwind Ltd",
"source": "website"
},
"notes": "Evaluating the team plan.",
"createdAt": "2026-02-18T12:41:09.000Z",
"updatedAt": "2026-04-22T14:05:33.000Z",
"lastMeetingAt": null
}
],
"meta": {
"totalRowCount": 24,
"limit": 10,
"offset": 0,
"hasMore": true
}
},
"message": "Contacts retrieved"
}{
"success": false,
"message": "<string>",
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}{
"success": false,
"message": "<string>",
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}{
"success": false,
"message": "Rate limit exceeded",
"error": {
"code": "TOO_MANY_REQUESTS",
"message": "Too many requests. Please retry after the rate limit window resets."
}
}List contacts
Lists the authenticated user’s contacts, with search across name, email, phone and notes, sorting, and createdAt/lastMeeting comparison filters. The payload is nested differently from the rest of the API: records live in data.rows and the counters in data.meta (totalRowCount, hasMore, limit, offset) — the top-level meta.pagination is not the one to read. Pagination is limit/offset, not page: limit defaults to 10 and is capped at 100, so ?limit=1000 returns 400.
curl --request GET \
--url https://api.cal.id/contacts/ \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.cal.id/contacts/"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.cal.id/contacts/', 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.id/contacts/",
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: Bearer <token>"
],
]);
$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.id/contacts/"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
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.id/contacts/")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cal.id/contacts/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"rows": [
{
"id": 3041,
"name": "Priya Sharma",
"email": "priya.sharma@example.com",
"phone": "+44 20 7946 0102",
"metadata": {
"company": "Northwind Ltd",
"source": "website"
},
"notes": "Met at the London meetup.",
"createdAt": "2026-02-18T12:41:09.000Z",
"updatedAt": "2026-04-22T14:05:33.000Z",
"lastMeetingAt": "2026-04-22T14:00:00.000Z"
},
{
"id": 3042,
"name": "Sam Okafor",
"email": "sam.okafor@example.com",
"phone": "+234 1 271 0000",
"metadata": {
"company": "Northwind Ltd",
"source": "website"
},
"notes": "Evaluating the team plan.",
"createdAt": "2026-02-18T12:41:09.000Z",
"updatedAt": "2026-04-22T14:05:33.000Z",
"lastMeetingAt": null
}
],
"meta": {
"totalRowCount": 24,
"limit": 10,
"offset": 0,
"hasMore": true
}
},
"message": "Contacts retrieved"
}{
"success": false,
"message": "<string>",
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}{
"success": false,
"message": "<string>",
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}{
"success": false,
"message": "Rate limit exceeded",
"error": {
"code": "TOO_MANY_REQUESTS",
"message": "Too many requests. Please retry after the rate limit window resets."
}
}Authorizations
Use the Authorization header with Bearer scheme.
Examples:
- API Key: Authorization: Bearer calid_xxxxx
Query Parameters
Search by name, email, phone, or notes.
"jane"
Field used for sorting contacts.
name, email, createdAt, updatedAt "name"
Sort direction.
asc, desc "asc"
Comparison operator for createdAtValue.
gt, lt "gt"
ISO datetime used with createdAtOperator.
"2026-05-01T00:00:00.000Z"
Comparison operator for lastMeetingValue.
gt, lt "lt"
ISO datetime used with lastMeetingOperator.
"2026-05-01T00:00:00.000Z"
Maximum number of contacts returned.
1 <= x <= 10010
Zero-based row offset.
x >= 00
Was this page helpful?