Skip to main content
The Users API allows you to retrieve and update user profile information.

​
API Version

User endpoints are available across all API versions: 
cal-api-version: 2024-08-13

​
Authentication

All user endpoints require authentication:
  • API Key: Pass via Authorization: Bearer <api-key> header
  • Access Token: OAuth access token
Required permissions:
  • PROFILE_READ for GET operations
  • PROFILE_WRITE for PATCH operations

​
Get My Profile

Retrieve the authenticated user’s profile information. 
curl --request GET \
  --url https://api.cal.com/v2/me \
  --header 'Authorization: Bearer <api-key>'

​
Response

​
status
string
Status of the response (“success”)
​
data
object
User profile data

​
Example Response

{
  "status": "success",
  "data": {
    "id": 123,
    "email": "[email protected]",
    "username": "alice",
    "name": "Alice Johnson",
    "timeZone": "America/New_York",
    "weekStart": "Monday",
    "timeFormat": 12,
    "defaultScheduleId": 456,
    "organizationId": 789,
    "organization": {
      "id": 789,
      "isPlatform": true
    }
  }
}

​
Update My Profile

Update the authenticated user’s profile. 
curl --request PATCH \
  --url https://api.cal.com/v2/me \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Alice Johnson",
    "timeZone": "Europe/London",
    "weekStart": "Monday"
  }'

​
Request Body

​
name
string
User’s full name
​
email
string
Email address. Changes require verification. The primary email stays unchanged until verification completes, unless the new email is already a verified secondary email or the user is platform-managed.
​
timeZone
string
User’s timezone (e.g., “America/New_York”, “Europe/London”)
​
weekStart
string
First day of the week: “Sunday”, “Monday”, “Tuesday”, etc.
​
timeFormat
number
Time format preference: 12 or 24
​
defaultScheduleId
number
ID of the schedule to set as default

​
Response

Returns the updated user profile with the same structure as the GET endpoint.

​
User Management

For team management features, see:
  • Teams API - Manage teams and team memberships

​
Managed Users

If you are a platform customer managing users:
  1. Create managed users through the platform management endpoints
  2. Set timezone when creating managed users to automatically create a default schedule
  3. Default schedules are created Monday-Friday, 9AM-5PM in the user’s timezone
  4. Without a default schedule, users cannot be booked or manage availability

​
Notes

  • Email changes require verification for security
  • Platform-managed users have different verification requirements
  • The defaultScheduleId links to the user’s primary availability schedule
  • Organization membership is read-only through this endpoint
  • Use the timezone format from the IANA timezone database (e.g., “America/New_York”)

Build docs developers (and LLMs) love

Get started for freeTalk to us