Skip to main content
POST
/
v2
/
oauth-clients
/
{clientId}
/
users
Create a managed user
curl --request POST \
  --url https://api.cal.com/v2/oauth-clients/{clientId}/users \
  --header 'Content-Type: application/json' \
  --header 'x-cal-secret-key: <x-cal-secret-key>' \
  --data '{
  "email": "[email protected]",
  "name": "Alice Smith",
  "timeFormat": 12,
  "weekStart": "Monday",
  "timeZone": "America/New_York",
  "locale": "en",
  "avatarUrl": "https://cal.com/api/avatar/2b735186-b01b-46d3-87da-019b8f61776b.png",
  "bio": "I am a bio",
  "metadata": {
    "key": "value"
  }
}'
{
  "status": "success",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
    "user": {
      "id": 1,
      "email": "[email protected]",
      "username": "alice",
      "name": "alice",
      "bio": "bio",
      "timeZone": "America/New_York",
      "weekStart": "Sunday",
      "createdDate": "2024-04-01T00:00:00.000Z",
      "timeFormat": 12,
      "defaultScheduleId": null,
      "locale": "en",
      "avatarUrl": "https://cal.com/api/avatar/2b735186-b01b-46d3-87da-019b8f61776b.png",
      "metadata": {
        "key": "value"
      }
    },
    "accessTokenExpiresAt": 123,
    "refreshTokenExpiresAt": 123
  },
  "error": {}
}

Headers

​
x-cal-secret-key
string
required

OAuth client secret key

Path Parameters

​
clientId
string
required

Body

application/json
​
email
string
required
​
name
string
required

Managed user's name is used in emails

Example:

"Alice Smith"

​
timeFormat
enum<number>

Must be a number 12 or 24

Available options:
12,
24
Example:

12

​
weekStart
enum<string>
Available options:
Monday,
Tuesday,
Wednesday,
Thursday,
Friday,
Saturday,
Sunday
Example:

"Monday"

​
timeZone
string

Timezone is used to create user's default schedule from Monday to Friday from 9AM to 5PM. If it is not passed then user does not have a default schedule and it must be created manually via the /schedules endpoint. Until the schedule is created, the user can't access availability atom to set his / her availability nor booked. It will default to Europe/London if not passed.

Example:

"America/New_York"

​
locale
enum<string>
Available options:
ar,
ca,
de,
es,
eu,
he,
id,
ja,
lv,
pl,
ro,
sr,
th,
vi,
az,
cs,
el,
es-419,
fi,
hr,
it,
km,
nl,
pt,
ru,
sv,
tr,
zh-CN,
bg,
da,
en,
et,
fr,
hu,
iw,
ko,
no,
pt-BR,
sk,
ta,
uk,
zh-TW,
bn
Example:

"en"

​
avatarUrl
string

URL of the user's avatar image

Example:

"https://cal.com/api/avatar/2b735186-b01b-46d3-87da-019b8f61776b.png"

​
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" }

Response

201 - application/json
​
status
enum<string>
required
Available options:
success,
error
Example:

"success"

​
data
object
required
​
error
object