Create a user - Cal.com Docs

POST

organizations

{orgId}

users

curl --request POST \
  --url https://api.cal.com/v2/organizations/{orgId}/users \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "[email protected]",
  "username": "user123",
  "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
}'

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

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

Body

application/json

string

required

User email address

Example:

"[email protected]"

username

string

Username

Example:

"user123"

weekday

string

Preferred weekday

Example:

"Monday"

brandColor

string

Brand color in HEX format

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

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

Response

201 - application/json

status

enum<string>

required

Available options:

success,

error

Example:

"success"

data

object

required

data.id

number

required

The ID of the user

Example:

1

data.email

string

required

The email of the user

Example:

"[email protected]"

data.timeZone

string

required

The time zone of the user

Example:

"America/New_York"

data.weekStart

string

required

The week start day of the user

Example:

"Monday"

data.hideBranding

boolean

required

Whether to hide branding for the user

Example:

false

data.createdDate

string

required

The date when the user was created

Example:

"2022-01-01T00:00:00Z"

data.profile

object

required

organization user profile, contains user data within the organizaton context

data.username

string | null

The username of the user

Example:

"john_doe"

data.name

string | null

The name of the user

Example:

"John Doe"

data.emailVerified

string | null

The date when the email was verified

Example:

"2022-01-01T00:00:00Z"

data.bio

string | null

The bio of the user

Example:

"I am a software developer"

data.avatarUrl

string | null

The URL of the user's avatar

Example:

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

data.appTheme

string | null

The app theme of the user

Example:

"light"

data.theme

string | null

The theme of the user

Example:

"default"

data.defaultScheduleId

number | null

The ID of the default schedule for the user

Example:

1

data.locale

string | null

The locale of the user

Example:

"en-US"

data.timeFormat

number | null

The time format of the user

Example:

12

data.brandColor

string | null

The brand color of the user

Example:

"#ffffff"

data.darkBrandColor

string | null

The dark brand color of the user

Example:

"#000000"

data.allowDynamicBooking

boolean | null

Whether dynamic booking is allowed for the user

Example:

true

data.verified

boolean | null

Whether the user is verified

Example:

true

data.invitedTo

number | null

The ID of the user who invited this user

Example:

1

data.metadata

object

Example:

{ "key": "value" }

Was this page helpful?

Suggest edits Raise issue

Get all users Delete a user

curl --request POST \
  --url https://api.cal.com/v2/organizations/{orgId}/users \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "[email protected]",
  "username": "user123",
  "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
}'

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

Getting Started

Platform / Managed Users

Platform / Webhooks

Orgs / Attributes

Orgs / Attributes / Options

Orgs / Bookings

Orgs / Delegation Credentials

Orgs / Memberships

Orgs / Orgs

Orgs / Routing forms

Orgs / Schedules

Orgs / Teams

Orgs / Teams / Bookings

Orgs / Teams / Event Types

Orgs / Teams / Memberships

Orgs / Teams / Routing forms

Orgs / Teams / Routing forms / Responses

Orgs / Teams / Users / Schedules

Orgs / Users

Orgs / Users / Bookings

Orgs / Users / OOO

Orgs / Users / Schedules

Orgs / Webhooks

Api Keys

Bookings

Calendars

Conferencing

Destination Calendars

Event Types

Event Types / Webhooks

Me

OAuth Clients

Organizations/Teams Conferencing

Schedules

Selected Calendars

Slots

Stripe

Teams

Teams / Event Types

Teams / Memberships

Webhooks

Headers

Body

Response