> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.slotflow.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.slotflow.dev/_mcp/server.

# Quickstart

> Go from zero to your first booking in 5 minutes.

This guide takes you from zero to a confirmed booking in 5 minutes. By the end, you'll have created a human, set their availability, found open slots, and booked one.

## Prerequisites

* A Slotflow account ([sign up free](https://slotflow.dev))
* Your API key (find it on the [dashboard](https://app.slotflow.dev))

## 1. Create a human

Humans represent the real people whose time can be booked. Create one for each team member.

**`cURL`**

```bash title="cURL"
curl -X POST https://api.slotflow.dev/v1/humans \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sarah Chen",
    "email": "sarah@acme.com",
    "role": "sales_rep",
    "timezone": "America/New_York"
  }'
```

**`Node.js`**

```javascript title="Node.js"
const response = await fetch("https://api.slotflow.dev/v1/humans", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Sarah Chen",
    email: "sarah@acme.com",
    role: "sales_rep",
    timezone: "America/New_York",
  }),
});

const human = await response.json();
console.log(human.id); // Save this — you'll need it for every subsequent call
```

**`Python`**

```python title="Python"
import requests

response = requests.post(
    "https://api.slotflow.dev/v1/humans",
    headers={
        "Authorization": "Bearer sk_live_your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "name": "Sarah Chen",
        "email": "sarah@acme.com",
        "role": "sales_rep",
        "timezone": "America/New_York",
    },
)

human = response.json()
print(human["id"])  # Save this
```

**`Node.js SDK`**

```typescript title="Node.js SDK"
import { SlotflowClient } from "slotflow";

const client = new SlotflowClient({ token: "sk_live_your_api_key" });

const human = await client.humans.createHuman({
  name: "Sarah Chen",
  email: "sarah@acme.com",
  role: "sales_rep",
  timezone: "America/New_York",
});
// Save human.data.id — you'll need it for every subsequent call
```

**`Python SDK`**

```python title="Python SDK"
from slotflow import Slotflow

client = Slotflow(api_key="sk_live_your_api_key")

human = client.humans.create(
    name="Sarah Chen",
    email="sarah@acme.com",
    role="sales_rep",
    timezone="America/New_York",
)
# Save human["id"] — you'll need it for every subsequent call
```

Save the `id` from the response — you'll need it for every subsequent call.

## 2. Set availability

Define when this human is available for meetings. This sets their base weekly schedule.

**`cURL`**

```bash title="cURL"
curl -X PUT https://api.slotflow.dev/v1/humans/HUMAN_ID/availability \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "working_days": [1, 2, 3, 4, 5],
    "work_start": "09:00",
    "work_end": "17:00",
    "meeting_durations": [30, 60]
  }'
```

**`Node.js`**

```javascript title="Node.js"
await fetch(`https://api.slotflow.dev/v1/humans/${humanId}/availability`, {
  method: "PUT",
  headers: {
    "Authorization": "Bearer sk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    working_days: [1, 2, 3, 4, 5],    // Monday through Friday
    work_start: "09:00",               // 9 AM in human's timezone
    work_end: "17:00",                 // 5 PM in human's timezone
    meeting_durations: [30, 60],       // 30-min and 60-min meetings
  }),
});
```

**`Python`**

```python title="Python"
requests.put(
    f"https://api.slotflow.dev/v1/humans/{human_id}/availability",
    headers={
        "Authorization": "Bearer sk_live_your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "working_days": [1, 2, 3, 4, 5],     # Monday through Friday
        "work_start": "09:00",                # 9 AM in human's timezone
        "work_end": "17:00",                  # 5 PM in human's timezone
        "meeting_durations": [30, 60],        # 30-min and 60-min meetings
    },
)
```

**`Node.js SDK`**

```typescript title="Node.js SDK"
await client.availability.setAvailability({
  humanId: humanId,
  working_days: [1, 2, 3, 4, 5],    // Monday through Friday
  work_start: "09:00",               // 9 AM in human's timezone
  work_end: "17:00",                 // 5 PM in human's timezone
  meeting_durations: [30, 60],       // 30-min and 60-min meetings
});
```

**`Python SDK`**

```python title="Python SDK"
client.availability.set(
    human["id"],
    working_days=[1, 2, 3, 4, 5],     # Monday through Friday
    work_start="09:00",                # 9 AM in human's timezone
    work_end="17:00",                  # 5 PM in human's timezone
    meeting_durations=[30, 60],        # 30-min and 60-min meetings
)
```

* `working_days`: 1=Monday through 7=Sunday
* `work_start` / `work_end`: HH:MM format in the human's timezone
* `meeting_durations`: array of allowed meeting lengths in minutes

## 3. Get available slots

This is the core endpoint. Your AI agent calls this to find when the human is free.

**`cURL`**

```bash title="cURL"
curl "https://api.slotflow.dev/v1/humans/HUMAN_ID/slots?date_from=2026-03-16&date_to=2026-03-20&duration=30" \
  -H "Authorization: Bearer sk_live_your_api_key"
```

**`Node.js`**

```javascript title="Node.js"
const params = new URLSearchParams({
  date_from: "2026-03-16",
  date_to: "2026-03-20",
  duration: "30",
});

const response = await fetch(
  `https://api.slotflow.dev/v1/humans/${humanId}/slots?${params}`,
  { headers: { "Authorization": "Bearer sk_live_your_api_key" } }
);

const { slots, timezone } = await response.json();
// slots = [{ starts_at: "2026-03-16T14:00:00.000Z", ends_at: "2026-03-16T14:30:00.000Z" }, ...]
```

**`Python`**

```python title="Python"
response = requests.get(
    f"https://api.slotflow.dev/v1/humans/{human_id}/slots",
    headers={"Authorization": "Bearer sk_live_your_api_key"},
    params={
        "date_from": "2026-03-16",
        "date_to": "2026-03-20",
        "duration": 30,
    },
)

data = response.json()
slots = data["slots"]  # List of available time slots in UTC
```

**`Node.js SDK`**

```typescript title="Node.js SDK"
const { slots, timezone } = await client.slots.getAvailableSlots({
  humanId: humanId,
  date_from: "2026-03-16",
  date_to: "2026-03-20",
  duration: 30,
});
// slots = [{ starts_at: "2026-03-16T14:00:00.000Z", ends_at: "..." }, ...]
```

**`Python SDK`**

```python title="Python SDK"
response = client.slots.list(
    human["id"],
    date_from="2026-03-16",
    date_to="2026-03-20",
    duration=30,
)
slots = response["slots"]
# [{"starts_at": "2026-03-16T14:00:00.000Z", "ends_at": "..."}, ...]
```

The response includes all available 30-minute slots for the week. Times are in UTC — use the `timezone` field to convert for display.

## 4. Book a slot

Pick a slot from the response and book it.

**`cURL`**

```bash title="cURL"
curl -X POST https://api.slotflow.dev/v1/bookings \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "human_id": "HUMAN_ID",
    "starts_at": "2026-03-16T14:00:00.000Z",
    "duration": 30,
    "attendee_name": "Alex Rivera",
    "attendee_email": "alex@startup.io",
    "metadata": {
      "source": "quickstart_guide"
    }
  }'
```

**`Node.js`**

```javascript title="Node.js"
const booking = await fetch("https://api.slotflow.dev/v1/bookings", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    human_id: humanId,
    starts_at: slots[0].starts_at,   // Use the first available slot
    duration: 30,
    attendee_name: "Alex Rivera",
    attendee_email: "alex@startup.io",
    metadata: {
      source: "quickstart_guide",
    },
  }),
}).then(r => r.json());

console.log(booking.id);     // Booking ID
console.log(booking.status); // "confirmed"
```

**`Python`**

```python title="Python"
response = requests.post(
    "https://api.slotflow.dev/v1/bookings",
    headers={
        "Authorization": "Bearer sk_live_your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "human_id": human_id,
        "starts_at": slots[0]["starts_at"],  # Use the first available slot
        "duration": 30,
        "attendee_name": "Alex Rivera",
        "attendee_email": "alex@startup.io",
        "metadata": {
            "source": "quickstart_guide",
        },
    },
)

booking = response.json()
print(booking["status"])  # "confirmed"
```

**`Node.js SDK`**

```typescript title="Node.js SDK"
const booking = await client.bookings.createBooking({
  human_id: humanId,
  starts_at: slots[0].starts_at,   // Use the first available slot
  duration: 30,
  attendee_name: "Alex Rivera",
  attendee_email: "alex@startup.io",
  metadata: { source: "quickstart_guide" },
});

console.log(booking.status); // "confirmed"
```

**`Python SDK`**

```python title="Python SDK"
booking = client.bookings.create(
    human_id=human["id"],
    starts_at=slots[0]["starts_at"],  # Use the first available slot
    duration=30,
    attendee_name="Alex Rivera",
    attendee_email="alex@startup.io",
    metadata={"source": "quickstart_guide"},
)

print(booking["status"])  # "confirmed"
```

The booking is confirmed immediately. The slot is no longer available for other bookings.

## 5. Verify on the dashboard

Open the [Slotflow Dashboard](https://app.slotflow.dev) and navigate to **Bookings**. You should see your new booking with status "confirmed".

## What's next?

#### [Authentication](/authentication)

Learn about API key management and security best practices.

#### [Node.js SDK](/sdk-node)

Use the official Node.js SDK for typed, zero-boilerplate integration.

#### [Python SDK](/sdk-python)

Use the official Python SDK with sync and async support.

#### [Agent Onboarding](/agent-onboarding)

Give your AI agent scheduling superpowers in 5 minutes.

#### [Webhooks](/webhooks)

Get notified when bookings are created or cancelled.