Create a booking | Slotflow Docs

Create a booking for a specific time slot. The API validates that:

The human exists and is active
The duration matches one of the human’s allowed meeting_durations
The time slot falls within working hours (or is covered by an open override)
No schedule block overrides conflict with the slot
No existing confirmed booking occupies the slot

If another booking was created for the same slot between your agent’s slot query and this request, you’ll receive a 409 SLOT_UNAVAILABLE error. Your agent should retry with the next available slot.

Metadata — pass arbitrary JSON (lead IDs, conversation IDs, ticket numbers) that your agent needs to maintain workflow context. This metadata is included in webhook payloads.

Plan limits — bookings count toward your monthly limit. On paid plans with auto-purchase enabled, overage packs ($19 per 500 bookings) are charged automatically when the limit is reached.

Create a booking for a specific time slot. The API validates that: 1. The human exists and is active 2. The duration matches one of the human's allowed `meeting_durations` 3. The time slot falls within working hours (or is covered by an open override) 4. No schedule block overrides conflict with the slot 5. No existing confirmed booking occupies the slot If another booking was created for the same slot between your agent's slot query and this request, you'll receive a `409 SLOT_UNAVAILABLE` error. Your agent should retry with the next available slot. **Metadata** — pass arbitrary JSON (lead IDs, conversation IDs, ticket numbers) that your agent needs to maintain workflow context. This metadata is included in webhook payloads. **Plan limits** — bookings count toward your monthly limit. On paid plans with auto-purchase enabled, overage packs ($19 per 500 bookings) are charged automatically when the limit is reached.

Authentication

AuthorizationBearer

API key authentication. Pass your key as a Bearer token:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx

Get your API key from the Slotflow Dashboard.

API key authentication. Pass your key as a Bearer token: ``` Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx ``` Get your API key from the [Slotflow Dashboard](https://app.slotflow.dev).

Request

This endpoint expects an object.

human_idstringRequiredformat: "uuid"

ID of the human to book

starts_atdatetimeRequired

Booking start time in ISO 8601 UTC format

durationintegerRequired

Meeting duration in minutes. Must match one of the human’s meeting_durations.

attendee_namestringRequired

Name of the person being booked

attendee_emailstringOptional

Email of the attendee (optional)

metadatamap from strings to anyOptional

Arbitrary JSON for your agent’s workflow state (lead IDs, conversation IDs, etc.)

Response

Booking confirmed

idstring or nullformat: "uuid"

human_idstring or nullformat: "uuid"

starts_atdatetime or null

Booking start time in UTC

ends_atdatetime or null

Booking end time in UTC

duration_minutesinteger or null

Duration in minutes

attendee_namestring or null

Name of the person being booked

attendee_emailstring or null

Email of the attendee (optional)

statusenum or null

Allowed values:

metadatamap from strings to any or null

Arbitrary JSON metadata passed by your agent for workflow tracking

created_atdatetime or null

Errors

Create a booking for a specific time slot. The API validates that:

The human exists and is active
The duration matches one of the human’s allowed meeting_durations
The time slot falls within working hours (or is covered by an open override)
No schedule block overrides conflict with the slot
No existing confirmed booking occupies the slot

Metadata — pass arbitrary JSON (lead IDs, conversation IDs, ticket numbers) that your agent needs to maintain workflow context. This metadata is included in webhook payloads.

Plan limits — bookings count toward your monthly limit. On paid plans with auto-purchase enabled, overage packs ($19 per 500 bookings) are charged automatically when the limit is reached.

1	import requests
2
3	url = "https://api.slotflow.dev/v1/v1/bookings"
4
5	payload = {
6	"human_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
7	"starts_at": "2026-03-10T14:00:00.000Z",
8	"duration": 30,
9	"attendee_name": "Alex Rivera",
10	"attendee_email": "alex@startup.io",
11	"metadata": {
12	"lead_id": "lead_8294",
13	"conversation_id": "conv_1847",
14	"source": "ai_sdr"
15	}
16	}
17	headers = {
18	"Authorization": "Bearer <token>",
19	"Content-Type": "application/json"
20	}
21
22	response = requests.post(url, json=payload, headers=headers)
23
24	print(response.json())

1	{
2	"id": "b9e4f2a1-3c5d-4e6f-8a9b-0c1d2e3f4a5b",
3	"human_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
4	"starts_at": "2026-03-10T14:00:00.000Z",
5	"ends_at": "2026-03-10T14:30:00.000Z",
6	"duration_minutes": 30,
7	"attendee_name": "Alex Rivera",
8	"attendee_email": "alex@startup.io",
9	"status": "confirmed",
10	"metadata": {
11	"lead_id": "lead_8294",
12	"conversation_id": "conv_1847",
13	"source": "ai_sdr"
14	},
15	"created_at": "2026-03-10T10:00:00.000Z"
16	}