Create a Booking

Create a new booking for a specific event type and time slot.

Endpoint


POST /api/public/scheduling/{userSlug}/{eventSlug}/book

Authentication: None required Rate Limit: 15 requests per minute per IP

Path Parameters

Parameter	Type	Description
`userSlug`	`string`	The user’s unique URL slug
`eventSlug`	`string`	The event type’s URL slug

Request Body


{
  "startTime": "2026-03-16T14:00:00Z",
  "endTime": "2026-03-16T14:30:00Z",
  "inviteeName": "Alex Johnson",
  "inviteeEmail": "alex@example.com",
  "inviteePhone": "+1-555-0123",
  "inviteeTimezone": "America/New_York",
  "inviteeLocale": "en",
  "customFields": {
    "company": "Acme Inc.",
    "role": "Engineering Manager"
  },
  "inviteeNotes": "I'd like to discuss the enterprise plan.",
  "source": "BookingPage",
  "honeypotValue": "",
  "captchaToken": "03AGdBq24..."
}

Request Fields

Field	Type	Required	Description
`startTime`	`string`	Yes	Slot start time in ISO 8601 UTC
`endTime`	`string`	Yes	Slot end time in ISO 8601 UTC
`inviteeName`	`string`	Yes	Guest’s full name
`inviteeEmail`	`string`	Yes	Guest’s email address
`inviteePhone`	`string`	No	Guest’s phone number
`inviteeTimezone`	`string`	Yes	Guest’s IANA timezone
`inviteeLocale`	`string`	No	Guest’s preferred locale (e.g., `en`, `de`, `es`)
`customFields`	`object`	No	Key-value pairs for custom booking form fields
`inviteeNotes`	`string`	No	Additional notes from the guest
`source`	`string`	No	Booking source: `BookingPage`, `EmbedWidget`, `API`
`honeypotValue`	`string`	No	Honeypot field value (must be empty for legitimate bookings)
`captchaToken`	`string`	No	CAPTCHA verification token (required if CAPTCHA is enabled)

Response

Returns 201 Created with the booking details.


{
  "id": "bkg_xyz789",
  "eventTypeId": "evt_abc123",
  "status": "Confirmed",
  "startTime": "2026-03-16T14:00:00Z",
  "endTime": "2026-03-16T14:30:00Z",
  "invitee": {
    "name": "Alex Johnson",
    "email": "alex@example.com",
    "phone": "+1-555-0123",
    "timezone": "America/New_York"
  },
  "location": {
    "type": "GoogleMeet",
    "value": "https://meet.google.com/abc-defg-hij"
  },
  "createdAt": "2026-03-13T10:30:00Z"
}

Booking Status Values

Status	Description
`Confirmed`	Booking is confirmed and both parties are notified
`PendingApproval`	Host has approval mode enabled; booking awaits host approval

Errors

Status	Description
`400`	Validation error (invalid times, missing required fields, slot no longer available)
`404`	User or event type not found
`429`	Rate limit exceeded

Example Error Response


{
  "error": "The selected time slot is no longer available."
}

Code Examples

cURL


curl -X POST https://app.proximity.io/api/public/scheduling/jane-doe/30min-call/book \
  -H "Content-Type: application/json" \
  -d '{
    "startTime": "2026-03-16T14:00:00Z",
    "endTime": "2026-03-16T14:30:00Z",
    "inviteeName": "Alex Johnson",
    "inviteeEmail": "alex@example.com",
    "inviteeTimezone": "America/New_York",
    "inviteeLocale": "en"
  }'

JavaScript


const response = await fetch(
  'https://app.proximity.io/api/public/scheduling/jane-doe/30min-call/book',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      startTime: '2026-03-16T14:00:00Z',
      endTime: '2026-03-16T14:30:00Z',
      inviteeName: 'Alex Johnson',
      inviteeEmail: 'alex@example.com',
      inviteeTimezone: 'America/New_York',
      inviteeLocale: 'en',
    }),
  }
);
 
if (response.status === 201) {
  const booking = await response.json();
  console.log(`Booking confirmed: ${booking.id}`);
} else {
  const error = await response.json();
  console.error(`Booking failed: ${error.error}`);
}

Python


import requests
 
response = requests.post(
    "https://app.proximity.io/api/public/scheduling/jane-doe/30min-call/book",
    json={
        "startTime": "2026-03-16T14:00:00Z",
        "endTime": "2026-03-16T14:30:00Z",
        "inviteeName": "Alex Johnson",
        "inviteeEmail": "alex@example.com",
        "inviteeTimezone": "America/New_York",
        "inviteeLocale": "en",
    },
)
 
if response.status_code == 201:
    booking = response.json()
    print(f"Booking confirmed: {booking['id']}")
else:
    print(f"Booking failed: {response.json()['error']}")