Schedule Management

This guide is a deep dive into Slotflow’s scheduling system — availability rules, schedule overrides (blocks and opens), and recurrence patterns. By the end, you’ll know how to model any real-world scheduling scenario.

The two layers

Slotflow uses a two-layer scheduling model:

1. Availability rules — the base weekly schedule (e.g., “Monday-Friday, 9am-5pm”)
2. Schedule overrides — exceptions to the base schedule (vacations, overtime, recurring meetings)

The slot engine combines both layers to compute what’s actually available on any given day.

Setting availability rules

Availability rules define the human’s repeating weekly schedule:

1
await fetch(`https://api.slotflow.dev/v1/humans/${humanId}/availability`, {
2
  method: "PUT",
3
  headers: {
4
    "Authorization": `Bearer ${process.env.SLOTFLOW_API_KEY}`,
5
    "Content-Type": "application/json",
6
  },
7
  body: JSON.stringify({
8
    working_days: [1, 2, 3, 4, 5],  // 1=Monday through 7=Sunday
9
    work_start: "09:00",             // In the human's timezone
10
    work_end: "17:00",
11
    meeting_durations: [30, 60],     // Allowed booking lengths in minutes
12
  }),
13
});

Important details:

• Times are in the human’s timezone (set when creating the human). Slotflow handles UTC conversion and DST automatically.
• meeting_durations controls what durations agents can book. If a human only takes 30-minute meetings, set [30].
• This is a full replace — send all fields every time. There’s no partial update.

Common availability patterns

Standard 9-5 weekdays:

1
{
2
  "working_days": [1, 2, 3, 4, 5],
3
  "work_start": "09:00",
4
  "work_end": "17:00",
5
  "meeting_durations": [30, 60]
6
}

Part-time (Mon/Wed/Fri mornings):

1
{
2
  "working_days": [1, 3, 5],
3
  "work_start": "08:00",
4
  "work_end": "12:00",
5
  "meeting_durations": [30]
6
}

Full week including weekends:

1
{
2
  "working_days": [1, 2, 3, 4, 5, 6, 7],
3
  "work_start": "10:00",
4
  "work_end": "18:00",
5
  "meeting_durations": [15, 30, 60]
6
}

Schedule overrides

Overrides handle everything the base schedule can’t — vacations, holidays, recurring internal meetings, overtime, special events.

Block overrides (remove availability)

All-day vacation

1
await fetch(`https://api.slotflow.dev/v1/humans/${humanId}/overrides`, {
2
  method: "POST",
3
  headers: {
4
    "Authorization": `Bearer ${process.env.SLOTFLOW_API_KEY}`,
5
    "Content-Type": "application/json",
6
  },
7
  body: JSON.stringify({
8
    type: "block",
9
    title: "Summer vacation",
10
    all_day: true,
11
    start_date: "2026-07-14",
12
    end_date: "2026-07-25",    // Date range — one row, not 12
13
  }),
14
});

Date ranges are stored as a single override, not one per day.

Time-specific block

Block a 2-hour window on a specific date:

1
{
2
  "type": "block",
3
  "title": "Dentist appointment",
4
  "all_day": false,
5
  "start_date": "2026-04-15",
6
  "start_time": "14:00",
7
  "end_time": "16:00"
8
}

The human is still available the rest of the day — only the 2-4pm window is blocked.

Recurring weekly block

Block every Tuesday 2-3pm for a team standup:

1
{
2
  "type": "block",
3
  "title": "Team standup",
4
  "all_day": false,
5
  "start_date": "2026-03-01",
6
  "start_time": "14:00",
7
  "end_time": "15:00",
8
  "recurrence": {
9
    "freq": "weekly",
10
    "days": [2]
11
  }
12
}

The start_date is when the recurrence begins. The override applies every Tuesday from that date onward.

Bi-weekly block

Block every other Monday morning for sprint planning:

1
{
2
  "type": "block",
3
  "title": "Sprint planning",
4
  "all_day": false,
5
  "start_date": "2026-03-02",
6
  "start_time": "09:00",
7
  "end_time": "10:30",
8
  "recurrence": {
9
    "freq": "weekly",
10
    "interval": 2,
11
    "days": [1]
12
  }
13
}

Monthly block

Block the first Friday of every month for an all-hands:

1
{
2
  "type": "block",
3
  "title": "Company all-hands",
4
  "all_day": false,
5
  "start_date": "2026-03-01",
6
  "start_time": "11:00",
7
  "end_time": "12:00",
8
  "recurrence": {
9
    "freq": "monthly",
10
    "week": 1,
11
    "day": 5
12
  }
13
}

Open overrides (add availability)

Open overrides let you add availability outside the base schedule — weekends, evenings, or any time that isn’t covered by the weekly rules.

Saturday overtime

1
{
2
  "type": "open",
3
  "title": "Saturday overtime",
4
  "all_day": false,
5
  "start_date": "2026-03-01",
6
  "start_time": "10:00",
7
  "end_time": "14:00",
8
  "recurrence": {
9
    "freq": "weekly",
10
    "days": [6]
11
  }
12
}

If the human’s base schedule is Monday-Friday, this adds Saturday 10am-2pm every week.

One-time evening event

1
{
2
  "type": "open",
3
  "title": "Evening office hours",
4
  "all_day": false,
5
  "start_date": "2026-04-10",
6
  "start_time": "18:00",
7
  "end_time": "20:00"
8
}

One-time availability on April 10th from 6-8pm, outside normal working hours.

How overrides interact with base schedule

The slot engine evaluates overrides in this order for each day:

1. All-day blocks — if matched, the entire day is skipped (no slots generated)
2. Base schedule — generate candidate slots from working days/hours
3. Time-specific blocks — remove slots that overlap with block windows
4. Open overrides — add extra slots from open windows (even on non-working days)
5. Deduplication — remove duplicate slots if open windows overlap base schedule
6. Booking conflicts — filter out slots occupied by confirmed bookings

Block overrides always take precedence over the base schedule. Open overrides add availability regardless of the base schedule.

Managing overrides

List all overrides for a human

1
const res = await fetch(
2
  `https://api.slotflow.dev/v1/humans/${humanId}/overrides`,
3
  { headers: { "Authorization": `Bearer ${process.env.SLOTFLOW_API_KEY}` } }
4
);
5
const { overrides, total } = await res.json();

Delete an override

1
await fetch(
2
  `https://api.slotflow.dev/v1/humans/${humanId}/overrides/${overrideId}`,
3
  {
4
    method: "DELETE",
5
    headers: { "Authorization": `Bearer ${process.env.SLOTFLOW_API_KEY}` },
6
  }
7
);

Deleting an override immediately changes slot availability. If you delete a block, those time slots become bookable again.

Real-world example

Here’s a complete setup for a sales rep named Sarah:

1
const API_KEY = process.env.SLOTFLOW_API_KEY;
2
const headers = {
3
  "Authorization": `Bearer ${API_KEY}`,
4
  "Content-Type": "application/json",
5
};
6
7
// Base schedule: Mon-Fri, 9am-5pm, 30-min and 60-min meetings
8
await fetch(`https://api.slotflow.dev/v1/humans/${sarahId}/availability`, {
9
  method: "PUT", headers,
10
  body: JSON.stringify({
11
    working_days: [1, 2, 3, 4, 5],
12
    work_start: "09:00",
13
    work_end: "17:00",
14
    meeting_durations: [30, 60],
15
  }),
16
});
17
18
// Block: Summer vacation (Jul 14-25)
19
await createOverride(sarahId, {
20
  type: "block", title: "Summer vacation",
21
  all_day: true, start_date: "2026-07-14", end_date: "2026-07-25",
22
});
23
24
// Block: Weekly team standup (Tuesdays 2-3pm)
25
await createOverride(sarahId, {
26
  type: "block", title: "Team standup",
27
  all_day: false, start_date: "2026-03-01",
28
  start_time: "14:00", end_time: "15:00",
29
  recurrence: { freq: "weekly", days: [2] },
30
});
31
32
// Block: Bi-weekly pipeline review (Mondays 9-10am)
33
await createOverride(sarahId, {
34
  type: "block", title: "Pipeline review",
35
  all_day: false, start_date: "2026-03-02",
36
  start_time: "09:00", end_time: "10:00",
37
  recurrence: { freq: "weekly", interval: 2, days: [1] },
38
});
39
40
// Open: Saturday morning overtime (10am-1pm)
41
await createOverride(sarahId, {
42
  type: "open", title: "Saturday overtime",
43
  all_day: false, start_date: "2026-03-01",
44
  start_time: "10:00", end_time: "13:00",
45
  recurrence: { freq: "weekly", days: [6] },
46
});
47
48
async function createOverride(humanId, data) {
49
  return fetch(`https://api.slotflow.dev/v1/humans/${humanId}/overrides`, {
50
    method: "POST", headers, body: JSON.stringify(data),
51
  });
52
}

With this setup, Sarah’s availability for a typical week looks like:

• Monday: 9-5pm (minus 9-10am on bi-weekly Mondays for pipeline review)
• Tuesday: 9-2pm + 3-5pm (team standup blocks 2-3pm every week)
• Wednesday-Friday: 9-5pm (full base schedule)
• Saturday: 10am-1pm (overtime window)
• Sunday: No availability

Key takeaways

• Availability rules are your base weekly schedule — set them once, they repeat forever
• Block overrides remove time — use for vacations, holidays, internal meetings
• Open overrides add time — use for overtime, special events, weekend hours
• Date ranges are single rows — a 2-week vacation is one override, not 14
• Recurrence handles repeating patterns — weekly standups, bi-weekly sprints, monthly all-hands
• Blocks win over base schedule — an all-day block cancels everything, including open overrides for that day