Skip to Content
Getting Started

Getting Started

This guide walks you through making your first API calls to fetch available time slots and create a booking.

Prerequisites

  • A Proximity account with at least one published event type
  • The user slug of the scheduler (found in the Proximity dashboard under Sharing)
  • The event slug of the event type you want to book

No API keys or tokens are required for public endpoints.

Step 1: Fetch the User Profile

Retrieve the scheduler’s public profile, including their available event types and branding:

curl https://app.proximity.io/api/public/scheduling/jane-doe

This returns the user’s event types, profile information, and branding settings. Use the slug from each event type for the next steps.

Step 2: Get Available Slots

Query available time slots for a specific event type:

curl "https://app.proximity.io/api/public/scheduling/jane-doe/30min-call/slots?\
dateFrom=2026-03-15&dateTo=2026-03-21&timezone=Europe/Berlin"

Required query parameters:

ParameterDescription
dateFromStart date in YYYY-MM-DD format
dateToEnd date in YYYY-MM-DD format
timezoneThe guest’s IANA timezone (e.g., America/New_York)

The response is grouped by date, with each date containing an array of available slots.

Step 3: Create a Booking

Once the guest picks a slot, create the booking:

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": "Europe/Berlin",
    "inviteeLocale": "en"
  }'

A successful booking returns 201 Created with the full booking details.

Step 4: Listen for Updates (Optional)

Set up webhooks to receive real-time notifications when bookings are created, cancelled, rescheduled, or approved.

JavaScript Example

const BASE = 'https://app.proximity.io/api/public/scheduling';
const USER = 'jane-doe';
const EVENT = '30min-call';
 
// Fetch available slots
const slotsRes = await fetch(
  `${BASE}/${USER}/${EVENT}/slots?dateFrom=2026-03-15&dateTo=2026-03-21&timezone=America/New_York`
);
const slots = await slotsRes.json();
 
// Pick the first available slot
const firstSlot = slots[0]?.slots[0];
 
if (firstSlot) {
  // Create a booking
  const bookingRes = await fetch(`${BASE}/${USER}/${EVENT}/book`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      startTime: firstSlot.startTime,
      endTime: firstSlot.endTime,
      inviteeName: 'Alex Johnson',
      inviteeEmail: 'alex@example.com',
      inviteeTimezone: 'America/New_York',
      inviteeLocale: 'en',
    }),
  });
 
  const booking = await bookingRes.json();
  console.log('Booking created:', booking.id);
}

Python Example

import requests
 
BASE = "https://app.proximity.io/api/public/scheduling"
USER = "jane-doe"
EVENT = "30min-call"
 
# Fetch available slots
slots = requests.get(f"{BASE}/{USER}/{EVENT}/slots", params={
    "dateFrom": "2026-03-15",
    "dateTo": "2026-03-21",
    "timezone": "America/New_York",
}).json()
 
# Pick the first available slot
first_slot = slots[0]["slots"][0]
 
# Create a booking
booking = requests.post(f"{BASE}/{USER}/{EVENT}/book", json={
    "startTime": first_slot["startTime"],
    "endTime": first_slot["endTime"],
    "inviteeName": "Alex Johnson",
    "inviteeEmail": "alex@example.com",
    "inviteeTimezone": "America/New_York",
    "inviteeLocale": "en",
}).json()
 
print(f"Booking created: {booking['id']}")

Next Steps

Last updated on
IntroductionAuthentication