Work with contacts

Contacts are the people you meet with. You can store their details, search across them, and see the meetings tied to each one. This guide shows you how to create, search, update, and delete contacts with the Cal ID API. Each contact is identified by its id. All requests use the base URL https://api.cal.id and are authenticated with a Bearer token.

Create a contact

Call POST /contacts/ with a JSON body. name and email are required; phone and notes are optional.

curl -X POST https://api.cal.id/contacts/ \
  -H "Authorization: Bearer calid_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+14155550123",
    "notes": "Prefers morning meetings."
  }'

async function createContact() {
  const res = await fetch("https://api.cal.id/contacts/", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CALID_KEY}`,
      // Mandatory on POST/PATCH — without it the API returns 415.
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Jane Doe",
      email: "jane@example.com",
      phone: "+14155550123",
      notes: "Prefers morning meetings.",
    }),
  });

  const body = await res.json();
  if (!res.ok) throw new Error(body.message ?? `HTTP ${res.status}`);
  return body.data;
}

createContact().then((contact) => console.log(contact.id));

import os
import requests

CALID_KEY = os.environ["CALID_KEY"]

response = requests.post(
    "https://api.cal.id/contacts/",
    headers={
        "Authorization": f"Bearer {CALID_KEY}",
        # Mandatory on POST/PATCH — without it the API returns 415.
        "Content-Type": "application/json",
    },
    json={
        "name": "Jane Doe",
        "email": "jane@example.com",
        "phone": "+14155550123",
        "notes": "Prefers morning meetings.",
    },
)
response.raise_for_status()

print(response.json()["data"]["id"])

On success, the created contact is returned in data, including its id. Save this id to look the contact up, update it, or list its meetings later.

{
  "success": true,
  "data": {
    "id": 789,
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+14155550123",
    "notes": "Prefers morning meetings."
  },
  "message": "Contact created successfully.",
  "meta": {}
}

Search contacts

Call GET /contacts/ to list your contacts. Pass search to match by name or email, and refine with sortBy, sortDirection, limit, and offset. This endpoint pages with limit/offset, not page.

curl -G https://api.cal.id/contacts/ \
  -H "Authorization: Bearer calid_xxxxx" \
  --data-urlencode "search=jane" \
  --data-urlencode "limit=20"

async function searchContacts() {
  // /contacts/ defaults to limit=10. The maximum is 100.
  const params = new URLSearchParams({ search: "jane", limit: "20" });

  const res = await fetch(`https://api.cal.id/contacts/?${params}`, {
    headers: { Authorization: `Bearer ${process.env.CALID_KEY}` },
  });

  const body = await res.json();
  if (!res.ok) throw new Error(body.message ?? `HTTP ${res.status}`);

  // Contacts nest: records in data.rows, counts in data.meta.
  return { contacts: body.data.rows, meta: body.data.meta };
}

searchContacts().then(({ contacts, meta }) =>
  console.log(`${contacts.length} of ${meta.totalRowCount}`, meta.hasMore)
);

import os
import requests

CALID_KEY = os.environ["CALID_KEY"]

# /contacts/ defaults to limit=10. The maximum is 100.
response = requests.get(
    "https://api.cal.id/contacts/",
    headers={"Authorization": f"Bearer {CALID_KEY}"},
    params={"search": "jane", "limit": 20},
)
response.raise_for_status()

# Contacts nest: records in data.rows, counts in data.meta.
data = response.json()["data"]
print(f"{len(data['rows'])} of {data['meta']['totalRowCount']}")
print("More pages:", data["meta"]["hasMore"])

Contacts are the one endpoint that nests twice: the records come back at data.rows and the counts at data.meta (totalRowCount, hasMore, limit, offset) — not at data[] and a top-level meta like the other list endpoints. Reading data[0] returns undefined rather than throwing, so this fails quietly.

Update or delete a contact

Use the contact’s id to change or remove it. Call PATCH /contacts/\{id\} with the fields you want to update.

curl -X PATCH https://api.cal.id/contacts/789 \
  -H "Authorization: Bearer calid_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Prefers afternoon meetings."
  }'

const contactId = 789;

async function updateContact() {
  const res = await fetch(`https://api.cal.id/contacts/${contactId}`, {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.CALID_KEY}`,
      // Mandatory on POST/PATCH — without it the API returns 415.
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ notes: "Prefers afternoon meetings." }),
  });

  const body = await res.json();
  if (!res.ok) throw new Error(body.message ?? `HTTP ${res.status}`);
  return body.data;
}

updateContact().then((contact) => console.log(contact));

import os
import requests

CALID_KEY = os.environ["CALID_KEY"]
contact_id = 789

response = requests.patch(
    f"https://api.cal.id/contacts/{contact_id}",
    headers={
        "Authorization": f"Bearer {CALID_KEY}",
        # Mandatory on POST/PATCH — without it the API returns 415.
        "Content-Type": "application/json",
    },
    json={"notes": "Prefers afternoon meetings."},
)
response.raise_for_status()

print(response.json()["data"])

To remove a contact, call DELETE /contacts/\{id\}.

curl -X DELETE https://api.cal.id/contacts/789 \
  -H "Authorization: Bearer calid_xxxxx"

const contactId = 789;

async function deleteContact() {
  const res = await fetch(`https://api.cal.id/contacts/${contactId}`, {
    method: "DELETE",
    headers: { Authorization: `Bearer ${process.env.CALID_KEY}` },
  });

  if (!res.ok) {
    const body = await res.json().catch(() => ({}));
    throw new Error(body.message ?? `HTTP ${res.status}`);
  }

  console.log("Contact deleted");
}

deleteContact();

import os
import requests

CALID_KEY = os.environ["CALID_KEY"]
contact_id = 789

response = requests.delete(
    f"https://api.cal.id/contacts/{contact_id}",
    headers={"Authorization": f"Bearer {CALID_KEY}"},
)
response.raise_for_status()

print("Contact deleted")

You can list a contact’s meetings with GET /contacts/\{id\}/meetings. This endpoint pages with limit/offset.

Contact endpoint references

Create a contact — full endpoint reference
List contacts — search and pagination options

Get started

Guides

Work with contacts

Contact endpoint references

​Contact endpoint references

Contact endpoint references