Create a membership

curl --request POST \
  --url https://api.cal.com/v2/organizations/{orgId}/memberships \
  --header 'Content-Type: application/json' \
  --data '
{
  "userId": 123,
  "role": "MEMBER",
  "accepted": false,
  "disableImpersonation": false
}
'

{
  "status": "success",
  "data": {
    "id": 123,
    "userId": 123,
    "teamId": 123,
    "accepted": true,
    "user": {
      "email": "<string>",
      "avatarUrl": "<string>",
      "username": "<string>",
      "name": "<string>",
      "bio": "<string>",
      "metadata": {
        "key": "value"
      }
    },
    "attributes": [
      {
        "id": "<string>",
        "name": "<string>",
        "type": "<string>",
        "option": "<string>",
        "optionId": "<string>"
      }
    ],
    "disableImpersonation": true
  }
}

Memberships

Create a membership

Required membership role: org admin. PBAC permission: organization.invite. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control. If accessed using an OAuth access token, the ORG_MEMBERSHIP_WRITE scope is required.

Two identifier modes are accepted in the request body:

userId — attach an existing user (by id) directly. Use when the caller already knows the Cal.com user id and just needs the membership row created/updated. No notification email is sent.
email — invite an existing Cal.com user (by email). Runs the same invite flow the dashboard uses; the user must already exist (if not, the request returns 404 — create them first via POST /v2/organizations/{orgId}/users). What happens next depends on the organization’s settings:
- Auto-attach path. When the organization is verified by Cal.com and the invitee’s email domain matches the organization’s configured auto-accept domain (both set by Cal.com during organization verification — not editable by the organization’s own admins), the user is added as an accepted member: their organization profile is created, the membership is created with accepted: true, and they receive a “you’ve been added to the organization” notification email.
- Pending-invite path. If either condition is not met, the user receives an “accept your invite” notification email and the membership is created with accepted: false until they accept it via the dashboard. No organization profile is created until acceptance.
Either way the response’s accepted value reflects the outcome, seat addition is recorded, and the new seat count is pushed to the billing provider.

POST

organizations

{orgId}

memberships

Create a membership

curl --request POST \
  --url https://api.cal.com/v2/organizations/{orgId}/memberships \
  --header 'Content-Type: application/json' \
  --data '
{
  "userId": 123,
  "role": "MEMBER",
  "accepted": false,
  "disableImpersonation": false
}
'

{
  "status": "success",
  "data": {
    "id": 123,
    "userId": 123,
    "teamId": 123,
    "accepted": true,
    "user": {
      "email": "<string>",
      "avatarUrl": "<string>",
      "username": "<string>",
      "name": "<string>",
      "bio": "<string>",
      "metadata": {
        "key": "value"
      }
    },
    "attributes": [
      {
        "id": "<string>",
        "name": "<string>",
        "type": "<string>",
        "option": "<string>",
        "optionId": "<string>"
      }
    ],
    "disableImpersonation": true
  }
}

Headers

Authorization

string

For non-platform customers - value must be Bearer <token> where <token> is api key prefixed with cal_

x-cal-secret-key

string

For platform customers - OAuth client secret key

x-cal-client-id

string

For platform customers - OAuth client ID

Path Parameters

orgId

number

required

Body

application/json

Either userId to attach an existing org user directly, or email to invite an existing Cal.com user via the dashboard's invite flow.

Option 1
Option 2

userId

number

required

role

enum<string>

default:MEMBER

required

If you are platform customer then managed users should only have MEMBER role.

Available options:

MEMBER,

OWNER,

ADMIN

accepted

boolean

default:false

disableImpersonation

boolean

default:false

Response

201 - application/json

status

enum<string>

required

Available options:

success,

error

Example:

"success"

data

object

required

Show child attributes

Get all memberships Get a membership

Documentation Index

Headers

Path Parameters

Body

Response