Manage team members

Use the Cal ID API to manage who belongs to a team and what they can do. Every request is authenticated with a Bearer token, and you must use a team owner or admin API key to manage that team’s memberships. All requests go to the base URL https://api.cal.id and include an Authorization: Bearer calid_xxxxx header. Requests with a JSON body must also send Content-Type: application/json, or they are rejected with 415 Unsupported Media Type. Successful responses wrap the result in a JSON envelope. The /teams/* endpoints return success, data, message, and — on list endpoints — a top-level meta.pagination. Read the result out of data; never off the top level.

{
  "success": true,
  "data": { },
  "meta": { },
  "message": "Request completed successfully"
}

The envelope is not identical across the whole API — some endpoints omit meta, some omit message, and unknown routes do not use the envelope at all. See Response format.

A team is identified by a teamId, and each membership within it is identified by a membershipId.

Team members can hold one of three roles:

MEMBER — the default role for a newly added member.
ADMIN — can manage the team and its members.
OWNER — full control over the team.

Add a member

Add a user to the team by their userId. The role field is optional and defaults to MEMBER.

curl -X POST "https://api.cal.id/teams/\{teamId\}/memberships" \
  -H "Authorization: Bearer calid_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"userId":321,"role":"MEMBER"}'

const teamId = 42;

async function addMember() {
  const res = await fetch(
    `https://api.cal.id/teams/${teamId}/memberships`,
    {
      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({ userId: 321, role: "MEMBER" }),
    }
  );

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

  // Read the membershipId out of data, not the body you sent.
  return body.data;
}

addMember().then((membership) => console.log(membership.id));

import os
import requests

CALID_KEY = os.environ["CALID_KEY"]
team_id = 42

response = requests.post(
    f"https://api.cal.id/teams/{team_id}/memberships",
    headers={
        "Authorization": f"Bearer {CALID_KEY}",
        # Mandatory on POST/PATCH — without it the API returns 415.
        "Content-Type": "application/json",
    },
    json={"userId": 321, "role": "MEMBER"},
)
response.raise_for_status()

# Read the membershipId out of data, not the body you sent.
print(response.json()["data"]["id"])

A successful create returns 201 and the new membership inside data, including the membershipId you need for the next two steps.

Response

{
  "success": true,
  "data": {
    "id": 987,
    "userId": 321,
    "role": "MEMBER"
  },
  "message": "Request completed successfully"
}

The exact fields inside data are listed on Add a team member. Read the identifier out of data, not out of the request body you sent.

List members

Retrieve the team’s memberships. This endpoint pages with page and limit and returns a top-level meta.pagination.

curl -G "https://api.cal.id/teams/\{teamId\}/memberships" \
  -H "Authorization: Bearer calid_xxxxx" \
  --data-urlencode "limit=100"

const teamId = 42;

async function listMembers() {
  // /teams/* lists default to limit=10. The maximum is 100.
  const params = new URLSearchParams({ limit: "100" });

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

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

  return { members: body.data, pagination: body.meta.pagination };
}

listMembers().then(({ members, pagination }) =>
  console.log(`${members.length} of ${pagination.total}`)
);

import os
import requests

CALID_KEY = os.environ["CALID_KEY"]
team_id = 42

# /teams/* lists default to limit=10. The maximum is 100.
response = requests.get(
    f"https://api.cal.id/teams/{team_id}/memberships",
    headers={"Authorization": f"Bearer {CALID_KEY}"},
    params={"limit": 100},
)
response.raise_for_status()

body = response.json()
print(f"{len(body['data'])} of {body['meta']['pagination']['total']}")

Response

{
  "success": true,
  "data": [ ],
  "meta": {
    "pagination": { "page": 1, "limit": 100, "total": 12, "totalPages": 1 }
  },
  "message": "Request completed successfully"
}

/teams/* list endpoints default to limit=10. A team with 25 members returns 10 unless you pass limit explicitly. The maximum is 100 — ?limit=1000 is rejected with 400 — querystring/limit must be <= 100.

Change a role

Update a member’s role by their membershipId. For example, promote a member to ADMIN.

curl -X PATCH "https://api.cal.id/teams/\{teamId\}/memberships/\{membershipId\}" \
  -H "Authorization: Bearer calid_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"role":"ADMIN"}'

const teamId = 42;
const membershipId = 987;

async function changeRole() {
  const res = await fetch(
    `https://api.cal.id/teams/${teamId}/memberships/${membershipId}`,
    {
      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({ role: "ADMIN" }),
    }
  );

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

changeRole().then((membership) => console.log(membership.role));

import os
import requests

CALID_KEY = os.environ["CALID_KEY"]
team_id = 42
membership_id = 987

response = requests.patch(
    f"https://api.cal.id/teams/{team_id}/memberships/{membership_id}",
    headers={
        "Authorization": f"Bearer {CALID_KEY}",
        # Mandatory on POST/PATCH — without it the API returns 415.
        "Content-Type": "application/json",
    },
    json={"role": "ADMIN"},
)
response.raise_for_status()

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

The updated membership comes back inside data.

Response

{
  "success": true,
  "data": {
    "id": 987,
    "userId": 321,
    "role": "ADMIN"
  },
  "message": "Request completed successfully"
}

Remove a member

Remove a member from the team by their membershipId.

curl -X DELETE "https://api.cal.id/teams/\{teamId\}/memberships/\{membershipId\}" \
  -H "Authorization: Bearer calid_xxxxx"

const teamId = 42;
const membershipId = 987;

async function removeMember() {
  const res = await fetch(
    `https://api.cal.id/teams/${teamId}/memberships/${membershipId}`,
    {
      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("Member removed");
}

removeMember();

import os
import requests

CALID_KEY = os.environ["CALID_KEY"]
team_id = 42
membership_id = 987

response = requests.delete(
    f"https://api.cal.id/teams/{team_id}/memberships/{membership_id}",
    headers={"Authorization": f"Bearer {CALID_KEY}"},
)
response.raise_for_status()

print("Member removed")

Get started

Guides

Manage team members

​Related endpoints

Related endpoints