Developer Platform & API Reference

SetSoon is built API-first. Every workflow possible in the administrative dashboard—calculating real-time availability, executing atomic slot holds, dispatching weighted round-robin bookings, and triggering multi-channel notifications—can be fully automated via our secure REST endpoints and webhooks.

Authentication

Authenticate all requests by including your API Secret Key in the standard HTTP Authorization header using the Bearer scheme:

HTTP Request Header

Authorization: Bearer sk_test_your_api_key_here

Idempotency Keys

SetSoon supports idempotent mutations. Include an Idempotency-Key UUID header on state-changing requests (`POST /api/v1/bookings`) to safely retry network failures without creating duplicate appointments.

Safety Guarantee: Re-sending an identical Idempotency-Key returns the cached result of the original transaction without re-allocating staff calendar slots or triggering duplicate customer confirmation emails.

POST /api/v1/availability/query

Calculates real-time available time windows factoring in service duration, provider schedules, multi-resource constraints, travel buffers, and active temporary holds.

cURL Request

curl -X POST https://setsoon.com/api/v1/availability/query \
  -H "Authorization: Bearer sk_test_demo_key" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "svc_strategy_60",
    "start_date": "2026-09-25",
    "end_date": "2026-09-26",
    "timezone": "America/New_York"
  }'

POST /api/v1/availability/inspect

Inspects a candidate time slot and returns a complete explainability breakdown covering staff schedule checks, room availability, equipment allocation, and buffer rules.

cURL Request

curl -X POST https://setsoon.com/api/v1/availability/inspect \
  -H "Authorization: Bearer sk_test_demo_key" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "svc_strategy_60",
    "start_time": "2026-09-25 10:00:00"
  }'

POST /api/v1/availability/simulate

Run hypothetical scenarios (e.g., adding staff or reducing buffer times from 30 min to 15 min) and calculate projected monthly meeting capacity increase.

cURL Request

curl -X POST https://setsoon.com/api/v1/availability/simulate \
  -H "Authorization: Bearer sk_test_demo_key" \
  -H "Content-Type: application/json" \
  -d '{
    "proposed_buffer_minutes": 15,
    "add_staff_count": 2
  }'

POST /api/v1/holds

Atomically locks a slot for up to 10 minutes while a prospective client fills out custom forms or completes credit card authorization, eliminating booking collisions.

cURL Request

curl -X POST https://setsoon.com/api/v1/holds \
  -H "Authorization: Bearer sk_test_demo_key" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": 1,
    "start_time": "2026-09-25 14:00:00",
    "end_time": "2026-09-25 15:00:00",
    "duration_minutes": 10
  }'

POST /api/v1/bookings

Confirms an appointment transactionally, assigns staff/room resources, triggers webhooks, and dispatches automated calendar invitations.

cURL Request

curl -X POST https://setsoon.com/api/v1/bookings \
  -H "Authorization: Bearer sk_test_demo_key" \
  -H "Idempotency-Key: e82491a2-3f19-4821-b489-0192841" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": 1,
    "start_time": "2026-09-25 14:00:00",
    "customer": {
      "name": "Morgan Blake",
      "email": "morgan@enterprise.com",
      "phone": "+14155550198"
    }
  }'

Webhook Delivery & HMAC-SHA256

SetSoon sends real-time HTTP POST events (`booking.created`, `booking.rescheduled`, `booking.cancelled`). Verify incoming event signatures to guarantee authenticity:

Node.js / Express Webhook Handler

const crypto = require('crypto');

function verifyWebhook(req, signingSecret) {
  const signature = req.headers['x-setsoon-signature'];
  const timestamp = req.headers['x-setsoon-timestamp'];
  const payload = req.rawBody;

  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(`${timestamp}.${payload}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Universal JavaScript Embed Widget

Add high-conversion, native booking flows to any webpage with one lightweight tag. No iframe boundaries or cookie restrictions:

HTML Embed Code

<!-- 1. Include SetSoon Universal SDK -->
<script src="https://setsoon.com/embed.js" async></script>

<!-- 2. Inline Booking Container -->
<div data-setsoon-embed="demo" data-theme="auto"></div>

<!-- 3. Or trigger as a seamless modal popup -->
<button onclick="SetSoon.openModal({ slug: 'demo' })">
  Book Strategy Call
</button>