> ## Documentation Index
> Fetch the complete documentation index at: https://developer.meetergo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Users

> Create and manage schedulable users via the API

Users are the foundation of scheduling in meetergo. Each user has their own availability schedule, meeting types, and booking URL.

## User Types

| Type | Description | Created Via |
| - | - | - |
| **Platform User** | API-created users for your platform's customers | `POST /v4/user` |
| **Regular User** | Dashboard users who sign up directly | Dashboard |

Platform users are designed for multi-tenant scenarios where you're building scheduling for your users.

## Create a User

Create a platform user with automatic defaults:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.meetergo.com/v4/user" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "email": "john.smith@example.com",
      "givenName": "John",
      "familyName": "Smith",
      "timezone": "Europe/Berlin"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.meetergo.com/v4/user', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email: 'john.smith@example.com',
      givenName: 'John',
      familyName: 'Smith',
      timezone: 'Europe/Berlin'
    })
  });
  ```
</CodeGroup>

### Request Body

| Field | Type | Required | Description |
| - | - | - | - |
| `email` | string | Yes | User's email address (must be unique) |
| `givenName` | string | Yes | First name |
| `familyName` | string | Yes | Last name |
| `timezone` | string | Yes | IANA timezone (e.g., `Europe/Berlin`, `America/New_York`) |
| `availability` | object | No | Custom availability schedule |
| `meetingType` | object | No | Custom meeting type |

### Response

```json theme={null}
{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "availabilityId": "660e8400-e29b-41d4-a716-446655440001",
  "meetingTypeId": "770e8400-e29b-41d4-a716-446655440002",
  "bookingUrl": "https://cal.meetergo.com/john-smith/30min-meeting",
  "companyId": "880e8400-e29b-41d4-a716-446655440003"
}
```

## Automatic Provisioning

When you create a user without custom settings, meetergo automatically creates:

| Resource | Default |
| - | - |
| **Availability** | Monday-Friday, 8:00-17:00 in user's timezone |
| **Meeting Type** | 30-minute meeting named "30min Meeting" |
| **Booking URL** | `https://cal.meetergo.com/{slug}/{meeting-slug}` |

## Custom Availability & Meeting Type

Specify custom availability and meeting type during creation:

```json theme={null}
{
  "email": "john.smith@example.com",
  "givenName": "John",
  "familyName": "Smith",
  "timezone": "Europe/Berlin",
  "availability": {
    "name": "Business Hours",
    "timezone": "Europe/Berlin",
    "schedule": {
      "monday": { "enabled": true, "hours": [{ "start": "09:00", "end": "12:00" }, { "start": "13:00", "end": "17:00" }] },
      "tuesday": { "enabled": true, "hours": [{ "start": "09:00", "end": "17:00" }] },
      "wednesday": { "enabled": true, "hours": [{ "start": "09:00", "end": "17:00" }] },
      "thursday": { "enabled": true, "hours": [{ "start": "09:00", "end": "17:00" }] },
      "friday": { "enabled": true, "hours": [{ "start": "09:00", "end": "15:00" }] },
      "saturday": { "enabled": false, "hours": [] },
      "sunday": { "enabled": false, "hours": [] }
    }
  },
  "meetingType": {
    "name": "Discovery Call",
    "duration": 45,
    "slug": "discovery-call",
    "channel": "phone"
  }
}
```

## Get Current User

Retrieve the authenticated user's details:

```bash theme={null}
curl -X GET "https://api.meetergo.com/v4/user/me" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "john.smith@example.com",
  "givenName": "John",
  "familyName": "Smith",
  "fullName": "John Smith",
  "timezone": "Europe/Berlin",
  "companyId": "880e8400-e29b-41d4-a716-446655440003",
  "createdAt": "2024-01-15T10:30:00Z"
}
```

## Update a User

Fix a typo or change a user's public booking slug:

```bash theme={null}
curl -X PATCH "https://api.meetergo.com/v4/user/{userId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "givenName": "Jonathan",
    "familyName": "Smith",
    "slug": "jonathan-smith"
  }'
```

### Editable Fields

| Field | Description |
| - | - |
| `givenName` | First name |
| `familyName` | Last name |
| `slug` | Public booking slug — min 5 characters, unique across the platform, normalized automatically |

All fields are optional; omitted fields stay unchanged. Any authenticated user can update their own profile; updating other users requires a company admin caller. The target user must belong to the caller's company.

<Info>
  **Email is not editable** via this endpoint — it affects the login identity and requires a separate flow. Contact support if you need to change a user's email.
</Info>

See the full [Update User reference](/api-reference/users/update-user) for response shape and error cases.

## Check Booking Availability

Query available time slots for a meeting type:

```bash theme={null}
curl -X GET "https://api.meetergo.com/v4/booking-availability?meetingTypeId={meetingTypeId}&start=2024-01-15&end=2024-01-20&timezone=Europe/Berlin" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Query Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `meetingTypeId` | string | Yes | The meeting type to check availability for |
| `start` | string | Yes | Start date (YYYY-MM-DD) |
| `end` | string | Yes | End date (YYYY-MM-DD) |
| `timezone` | string | No | Return times in this timezone |
| `hostIds` | string | No | Comma-separated host user IDs |

### Response

```json theme={null}
{
  "timezone": "Europe/Berlin",
  "timeframes": [
    {
      "start": "2024-01-15T08:00:00.000Z",
      "end": "2024-01-15T16:00:00.000Z"
    }
  ],
  "dates": [
    {
      "date": "2024-01-15",
      "spots": [
        { "startTime": "2024-01-15T09:00:00.000+01:00" },
        { "startTime": "2024-01-15T09:30:00.000+01:00" },
        { "startTime": "2024-01-15T10:00:00.000+01:00" },
        { "startTime": "2024-01-15T10:30:00.000+01:00" },
        { "startTime": "2024-01-15T11:00:00.000+01:00" }
      ]
    }
  ],
  "earliestAvailableDate": "2024-01-15"
}
```

## Timezones

Use valid IANA timezone identifiers:

| Example | Region |
| - | - |
| `Europe/Berlin` | Germany |
| `Europe/London` | UK |
| `America/New_York` | US East Coast |
| `America/Los_Angeles` | US West Coast |
| `Asia/Tokyo` | Japan |
| `Australia/Sydney` | Australia |

<Warning>
  Invalid timezones will return a 400 error. See [IANA timezone database](https://www.iana.org/time-zones) for the full list.
</Warning>

## Best Practices

<Check>
  **Store user IDs** - Save the `userId` returned from user creation to reference the user later
</Check>

<Check>
  **Use appropriate timezones** - Set the timezone based on where your user is located
</Check>

<Check>
  **Customize for your use case** - Use custom availability and meeting types that match your business needs
</Check>

<Warning>
  **Email uniqueness** - Each user email must be unique within your company
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.