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

# Availability

> Configure when users can be booked with weekly schedules and exceptions

Availability defines when a user can be booked. It consists of a weekly recurring schedule with optional date-based exceptions for holidays or custom hours.

## Availability Structure

| Component           | Description                                       |
| ------------------- | ------------------------------------------------- |
| **Weekly Schedule** | Recurring hours for each day of the week          |
| **Timezone**        | All times are interpreted in this timezone        |
| **Exceptions**      | Date-specific overrides (holidays, special hours) |

## Default Availability

When you create a user without specifying availability, meetergo creates a default schedule:

* **Monday-Friday**: 8:00-17:00
* **Saturday-Sunday**: Unavailable
* **Timezone**: User's specified timezone

## Get User Availability

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

### Response

```json theme={null}
{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "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": [] }
  }
}
```

## Update Availability

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.meetergo.com/v4/availability/{availabilityId}" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "x-meetergo-api-user-id: {userId}" \
    -H "Content-Type: application/json" \
    -d '{
      "schedule": {
        "monday": { "enabled": true, "hours": [{ "start": "10:00", "end": "18:00" }] },
        "tuesday": { "enabled": true, "hours": [{ "start": "10:00", "end": "18:00" }] },
        "wednesday": { "enabled": true, "hours": [{ "start": "10:00", "end": "18:00" }] },
        "thursday": { "enabled": true, "hours": [{ "start": "10:00", "end": "18:00" }] },
        "friday": { "enabled": true, "hours": [{ "start": "10:00", "end": "16:00" }] },
        "saturday": { "enabled": false, "hours": [] },
        "sunday": { "enabled": false, "hours": [] }
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  await fetch(`https://api.meetergo.com/v4/availability/${availabilityId}`, {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'x-meetergo-api-user-id': userId,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      schedule: {
        monday: { enabled: true, hours: [{ start: '10:00', end: '18:00' }] },
        tuesday: { enabled: true, hours: [{ start: '10:00', end: '18:00' }] },
        wednesday: { enabled: true, hours: [{ start: '10:00', end: '18:00' }] },
        thursday: { enabled: true, hours: [{ start: '10:00', end: '18:00' }] },
        friday: { enabled: true, hours: [{ start: '10:00', end: '16:00' }] },
        saturday: { enabled: false, hours: [] },
        sunday: { enabled: false, hours: [] }
      }
    })
  });
  ```
</CodeGroup>

## Schedule Format

The schedule is an object with a property for each day of the week.

### Day Properties

| Property    | Description        |
| ----------- | ------------------ |
| `monday`    | Monday schedule    |
| `tuesday`   | Tuesday schedule   |
| `wednesday` | Wednesday schedule |
| `thursday`  | Thursday schedule  |
| `friday`    | Friday schedule    |
| `saturday`  | Saturday schedule  |
| `sunday`    | Sunday schedule    |

### Day Schedule Structure

Each day has two properties:

| Field     | Type    | Description                              |
| --------- | ------- | ---------------------------------------- |
| `enabled` | boolean | Whether the day is available for booking |
| `hours`   | array   | Time ranges when available               |

### Time Format

Times use 24-hour format: `HH:MM`

| Example | Meaning  |
| ------- | -------- |
| `09:00` | 9:00 AM  |
| `13:30` | 1:30 PM  |
| `17:00` | 5:00 PM  |
| `23:59` | 11:59 PM |

### Multiple Time Ranges Per Day

Support lunch breaks or split schedules by adding multiple entries to the `hours` array:

```json theme={null}
{
  "monday": {
    "enabled": true,
    "hours": [
      { "start": "09:00", "end": "12:00" },
      { "start": "13:00", "end": "17:00" }
    ]
  }
}
```

## Common Patterns

### Standard Business Hours

```json theme={null}
{
  "schedule": {
    "monday": { "enabled": true, "hours": [{ "start": "09: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": "17:00" }] },
    "saturday": { "enabled": false, "hours": [] },
    "sunday": { "enabled": false, "hours": [] }
  }
}
```

### With Lunch Break

```json theme={null}
{
  "monday": {
    "enabled": true,
    "hours": [
      { "start": "09:00", "end": "12:00" },
      { "start": "13:00", "end": "17:00" }
    ]
  }
}
```

### Extended Evening Hours

```json theme={null}
{
  "monday": { "enabled": true, "hours": [{ "start": "10:00", "end": "20:00" }] },
  "tuesday": { "enabled": true, "hours": [{ "start": "10:00", "end": "20:00" }] }
}
```

### Weekend Availability

```json theme={null}
{
  "saturday": { "enabled": true, "hours": [{ "start": "10:00", "end": "14:00" }] },
  "sunday": { "enabled": true, "hours": [{ "start": "10:00", "end": "14:00" }] }
}
```

## Exceptions-Only Availability

For ticket-based or one-off booking scenarios, you can create availability with specific datetime windows only—no recurring weekly schedule.

When `schedule` is omitted from availability creation, all days default to disabled. Only the specified `exceptions` define available booking windows.

### Creating Exceptions-Only Availability

When [creating a meeting type](/api-reference/meeting-types/create-meeting-type) with inline availability:

```json theme={null}
{
  "meetingInfo": {
    "name": "Property Evaluation",
    "description": "On-site property evaluation",
    "duration": 60,
    "channel": "phone"
  },
  "availability": {
    "name": "Ticket Availability",
    "timezone": "Europe/Berlin",
    "exceptions": [
      { "available": true, "start": "2026-01-27T10:00", "end": "2026-01-27T11:00" },
      { "available": true, "start": "2026-01-27T14:00", "end": "2026-01-27T15:00" },
      { "available": true, "start": "2026-01-28T09:00", "end": "2026-01-28T10:00" }
    ]
  },
  "metadata": {
    "ticketId": "EVAL-12345"
  }
}
```

<Note>
  When `schedule` is omitted, the weekly schedule defaults to all days disabled. Bookings are only possible during the specified exception windows.
</Note>

### Exception Fields

| Field       | Type    | Required | Description                                         |
| ----------- | ------- | -------- | --------------------------------------------------- |
| `available` | boolean | Yes      | `true` to make the time available, `false` to block |
| `start`     | string  | Yes      | Start datetime (e.g., `2026-01-27T10:00`)           |
| `end`       | string  | Yes      | End datetime (e.g., `2026-01-27T11:00`)             |
| `title`     | string  | No       | Optional label for the exception                    |
| `note`      | string  | No       | Optional internal note                              |

### Use Cases

**Ticket-based scheduling:**

* Property evaluations with specific appointment slots
* Support callbacks with limited time windows
* One-time consultations with pre-defined availability

**Holiday overrides:**

* Block time during holidays with `available: false`
* Add special holiday hours with `available: true`

## Booking Availability

Once availability is set, query available booking slots:

```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"
```

The API returns slots based on:

1. **Availability schedule** - User's weekly hours
2. **Existing bookings** - Slots already booked are excluded
3. **Meeting type duration** - Slots fit the meeting length
4. **Buffer times** - Meeting type buffers are respected
5. **Calendar integrations** - Connected calendars block time

### 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" }
      ]
    }
  ],
  "earliestAvailableDate": "2024-01-15"
}
```

## Timezone Handling

All availability times are interpreted in the user's configured timezone.

**Example:**

* User timezone: `Europe/Berlin` (UTC+1)
* Availability: 9:00-17:00
* A customer in `America/New_York` (UTC-5) sees: 3:00 AM - 11:00 AM

<Tip>
  The API handles timezone conversion automatically. Always store and display times in the customer's local timezone for the best experience.
</Tip>

## Best Practices

<Check>
  **Set realistic hours** - Only mark times when the user will actually be available
</Check>

<Check>
  **Include buffer time** - Don't schedule wall-to-wall meetings
</Check>

<Check>
  **Consider timezones** - If serving global customers, consider extended hours or multiple time windows
</Check>

<Warning>
  **Empty schedules** - If no intervals are defined for any day and no exceptions are specified, the user won't have any available slots. Use [exceptions-only availability](#exceptions-only-availability) for ticket-based scheduling with specific time windows.
</Warning>