> ## 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>