Create a user

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.

This endpoint creates a brand-new Cal.com user account and attaches them to the organization. If the email already belongs to an existing Cal.com user, the request fails with 400 user_already_invited_or_member. A common case is re-adding someone who was previously removed from the organization via the dashboard: the membership is gone, but the underlying Cal.com user account still exists.

To attach an existing Cal.com user to the organization, use POST /v2/organizations/{orgId}/memberships with the email field instead.

POST /v2/organizations/{orgId}/users

Create a user

cURL

curl --request POST \
  --url https://api.cal.com/v2/organizations/{orgId}/users \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "[e-mail]",
  "username": "user123",
  "name": "Alice Smith",
  "weekday": "Monday",
  "brandColor": "#FFFFFF",
  "bio": "I am a bio",
  "metadata": {
    "key": "value"
  },
  "darkBrandColor": "#000000",
  "hideBranding": false,
  "timeZone": "America/New_York",
  "theme": "dark",
  "appTheme": "light",
  "timeFormat": 24,
  "defaultScheduleId": 1,
  "locale": "en",
  "avatarUrl": "https://example.com/avatar.jpg",
  "organizationRole": "MEMBER",
  "autoAccept": true,
  "skipNotificationEmail": false
}
'

import requests

url = "https://api.cal.com/v2/organizations/{orgId}/users"

payload = {
    "email": "[e-mail]",
    "username": "user123",
    "name": "Alice Smith",
    "weekday": "Monday",
    "brandColor": "#FFFFFF",
    "bio": "I am a bio",
    "metadata": { "key": "value" },
    "darkBrandColor": "#000000",
    "hideBranding": False,
    "timeZone": "America/New_York",
    "theme": "dark",
    "appTheme": "light",
    "timeFormat": 24,
    "defaultScheduleId": 1,
    "locale": "en",
    "avatarUrl": "https://example.com/avatar.jpg",
    "organizationRole": "MEMBER",
    "autoAccept": True,
    "skipNotificationEmail": False
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    email: '[e-mail]',
    username: 'user123',
    name: 'Alice Smith',
    weekday: 'Monday',
    brandColor: '#FFFFFF',
    bio: 'I am a bio',
    metadata: {key: 'value'},
    darkBrandColor: '#000000',
    hideBranding: false,
    timeZone: 'America/New_York',
    theme: 'dark',
    appTheme: 'light',
    timeFormat: 24,
    defaultScheduleId: 1,
    locale: 'en',
    avatarUrl: 'https://example.com/avatar.jpg',
    organizationRole: 'MEMBER',
    autoAccept: true,
    skipNotificationEmail: false
  })
};

fetch('https://api.cal.com/v2/organizations/{orgId}/users', 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/organizations/{orgId}/users",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'email' => '[e-mail]',
    'username' => 'user123',
    'name' => 'Alice Smith',
    'weekday' => 'Monday',
    'brandColor' => '#FFFFFF',
    'bio' => 'I am a bio',
    'metadata' => [
        'key' => 'value'
    ],
    'darkBrandColor' => '#000000',
    'hideBranding' => false,
    'timeZone' => 'America/New_York',
    'theme' => 'dark',
    'appTheme' => 'light',
    'timeFormat' => 24,
    'defaultScheduleId' => 1,
    'locale' => 'en',
    'avatarUrl' => 'https://example.com/avatar.jpg',
    'organizationRole' => 'MEMBER',
    'autoAccept' => true,
    'skipNotificationEmail' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cal.com/v2/organizations/{orgId}/users"

	payload := strings.NewReader("{\n  \"email\": \"[e-mail]\",\n  \"username\": \"user123\",\n  \"name\": \"Alice Smith\",\n  \"weekday\": \"Monday\",\n  \"brandColor\": \"#FFFFFF\",\n  \"bio\": \"I am a bio\",\n  \"metadata\": {\n    \"key\": \"value\"\n  },\n  \"darkBrandColor\": \"#000000\",\n  \"hideBranding\": false,\n  \"timeZone\": \"America/New_York\",\n  \"theme\": \"dark\",\n  \"appTheme\": \"light\",\n  \"timeFormat\": 24,\n  \"defaultScheduleId\": 1,\n  \"locale\": \"en\",\n  \"avatarUrl\": \"https://example.com/avatar.jpg\",\n  \"organizationRole\": \"MEMBER\",\n  \"autoAccept\": true,\n  \"skipNotificationEmail\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cal.com/v2/organizations/{orgId}/users")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"[e-mail]\",\n  \"username\": \"user123\",\n  \"name\": \"Alice Smith\",\n  \"weekday\": \"Monday\",\n  \"brandColor\": \"#FFFFFF\",\n  \"bio\": \"I am a bio\",\n  \"metadata\": {\n    \"key\": \"value\"\n  },\n  \"darkBrandColor\": \"#000000\",\n  \"hideBranding\": false,\n  \"timeZone\": \"America/New_York\",\n  \"theme\": \"dark\",\n  \"appTheme\": \"light\",\n  \"timeFormat\": 24,\n  \"defaultScheduleId\": 1,\n  \"locale\": \"en\",\n  \"avatarUrl\": \"https://example.com/avatar.jpg\",\n  \"organizationRole\": \"MEMBER\",\n  \"autoAccept\": true,\n  \"skipNotificationEmail\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cal.com/v2/organizations/{orgId}/users")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"[e-mail]\",\n  \"username\": \"user123\",\n  \"name\": \"Alice Smith\",\n  \"weekday\": \"Monday\",\n  \"brandColor\": \"#FFFFFF\",\n  \"bio\": \"I am a bio\",\n  \"metadata\": {\n    \"key\": \"value\"\n  },\n  \"darkBrandColor\": \"#000000\",\n  \"hideBranding\": false,\n  \"timeZone\": \"America/New_York\",\n  \"theme\": \"dark\",\n  \"appTheme\": \"light\",\n  \"timeFormat\": 24,\n  \"defaultScheduleId\": 1,\n  \"locale\": \"en\",\n  \"avatarUrl\": \"https://example.com/avatar.jpg\",\n  \"organizationRole\": \"MEMBER\",\n  \"autoAccept\": true,\n  \"skipNotificationEmail\": false\n}"

response = http.request(request)
puts response.read_body

201

{
  "status": "success",
  "data": {
    "id": 1,
    "email": "[e-mail]",
    "timeZone": "America/New_York",
    "weekStart": "Monday",
    "hideBranding": false,
    "createdDate": "2022-01-01T00:00:00Z",
    "profile": {
      "id": 1,
      "organizationId": 1,
      "userId": 1,
      "username": "john_doe"
    },
    "username": "john_doe",
    "name": "John Doe",
    "emailVerified": "2022-01-01T00:00:00Z",
    "bio": "I am a software developer",
    "avatarUrl": "https://example.com/avatar.jpg",
    "appTheme": "light",
    "theme": "default",
    "defaultScheduleId": 1,
    "locale": "en-US",
    "timeFormat": 12,
    "brandColor": "#ffffff",
    "darkBrandColor": "#000000",
    "allowDynamicBooking": true,
    "verified": true,
    "invitedTo": 1,
    "metadata": {
      "key": "value"
    }
  }
}

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

email · string<email> · required

User email address

Example:

"[e-mail]"

username · string

Username

Example:

"user123"

name · string

Full name of the user

Maximum string length: 50

Example:

"Alice Smith"

weekday · string

Preferred weekday

Example:

"Monday"

brandColor · string

Brand color in HEX format

Pattern: ^#?([0-9A-F]{3}|[0-9A-F]{4}|[0-9A-F]{6}|[0-9A-F]{8})$

Example:

"#FFFFFF"

bio · string

Bio

Example:

"I am a bio"

metadata · object

You can store any additional data you want here. Metadata must have at most 50 keys, each key up to 40 characters, and values up to 500 characters.

Example:

{ "key": "value" }

darkBrandColor · string

Dark brand color in HEX format

Pattern: ^#?([0-9A-F]{3}|[0-9A-F]{4}|[0-9A-F]{6}|[0-9A-F]{8})$

Example:

"#000000"

hideBranding · boolean

Hide branding

Example:

false

timeZone · string

Time zone

Example:

"America/New_York"

theme · string | null

Theme

Example:

"dark"

appTheme · string | null

Application theme

Example:

"light"

timeFormat · number

Time format

Example:

24

defaultScheduleId · number

Default schedule ID

Required range: x >= 0

Example:

1

locale · string | null · default: en

Locale

Example:

"en"

avatarUrl · string

Avatar URL

Example:

"https://example.com/avatar.jpg"

organizationRole · enum<string> · default: MEMBER

Available options: MEMBER, ADMIN, OWNER

autoAccept · boolean · default: true

Must be true to ensure the organization membership is created in accepted state. If false, the user will have a pending membership and will not be able to access the organization.

skipNotificationEmail · boolean · default: false

If true, the signup notification email will not be sent to the new user.

Response

201 - application/json

status · enum<string> · required

Available options: success, error

Example:

"success"

data · object · required

Show child attributes