DEVELOPER PORTAL

Build on SwiftGuest

A REST API with 255+ endpoints, official SDKs for four languages, OAuth 2.0, webhooks, and documentation that respects your time. Ship your integration in hours, not weeks.

Quick start GitHub Webhooks

255+

REST Endpoints

Official SDKs

1k/min

Rate Limit

Webhook Events

terminal ~ create reservation

curl https://api.swiftguest.com/v1/reservations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "property_id": "prop_8hJk3m",
    "guest": {
      "first_name": "Ada",
      "last_name": "Lovelace",
      "email": "ada@example.com"
    },
    "check_in": "2026-05-10",
    "check_out": "2026-05-14",
    "room_type_id": "rt_standard",
    "adults": 2,
    "rate_plan_id": "rp_bar"
  }'

POST /v1/reservations — try the first call in under 60 seconds.

REST API Reference

Every endpoint documented with request, response, and example payloads. OpenAPI 3.0 specification available for generating clients.

Browse endpoints

Official SDKs

Type-safe clients for JavaScript, Python, Go, and PHP. Built-in retry, pagination, and automatic token refresh.

View SDKs

Webhook Events

Subscribe to reservation, payment, guest, and housekeeping events. HMAC-signed payloads with automatic retry.

Webhooks reference

OAuth 2.0

Build integrations that multiple properties can authorize. Authorization code flow, refresh tokens, and scoped access.

Authentication guide

QUICK START

Your first API call, three ways

Grab an API token from your dashboard, pick a language, paste the snippet, and you have a working reservation in your sandbox. Real endpoint. Real response. Switch tabs to see the same call in your preferred stack.

cURL

shell

curl https://api.swiftguest.com/v1/reservations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "property_id": "prop_8hJk3m",
    "guest": {
      "first_name": "Ada",
      "last_name": "Lovelace",
      "email": "ada@example.com"
    },
    "check_in": "2026-05-10",
    "check_out": "2026-05-14",
    "room_type_id": "rt_standard",
    "adults": 2,
    "rate_plan_id": "rp_bar"
  }'

JavaScript / Node

typescript

import { SwiftGuest } from "@swiftguest/sdk";

const client = new SwiftGuest({
  apiKey: process.env.SWIFTGUEST_TOKEN,
});

// Create a reservation
const reservation = await client.reservations.create({
  property_id: "prop_8hJk3m",
  guest: {
    first_name: "Ada",
    last_name: "Lovelace",
    email: "ada@example.com",
  },
  check_in: "2026-05-10",
  check_out: "2026-05-14",
  room_type_id: "rt_standard",
  adults: 2,
  rate_plan_id: "rp_bar",
});

console.log(reservation.id);
// Paginate through future arrivals
for await (const r of client.reservations.list({ status: "confirmed" })) {
  console.log(r.id, r.check_in);
}

Python

python

from swiftguest import SwiftGuest

client = SwiftGuest(api_key="YOUR_TOKEN")

reservation = client.reservations.create(
    property_id="prop_8hJk3m",
    guest={
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "ada@example.com",
    },
    check_in="2026-05-10",
    check_out="2026-05-14",
    room_type_id="rt_standard",
    adults=2,
    rate_plan_id="rp_bar",
)

print(reservation.id)

# Auto-paginating list
for r in client.reservations.list(status="confirmed"):
    print(r.id, r.check_in)

Prefer the full reference?

Browse every endpoint, request parameter, and response schema in the API reference.

Open reference

AUTHENTICATION

API keys and OAuth 2.0

Two ways to authenticate. Use API keys for first-party integrations where you control both the server and the SwiftGuest account. Use OAuth 2.0 when you're building an app that multiple properties will install.

Bearer token in the Authorization header
Scoped permissions per key or per OAuth client
Short-lived access tokens with refresh token rotation
IP allow-lists for server-to-server keys
Automatic key rotation helpers in every SDK

Header format

Authorization: Bearer YOUR_TOKEN

oauth 2.0 flow

# Step 1 — redirect the user to authorize
https://api.swiftguest.com/oauth/authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=reservations:read+payments:write
  &state=RANDOM_STATE

# Step 2 — exchange the returned code for an access token
POST https://api.swiftguest.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=https://yourapp.com/callback

# Response
{
  "access_token":  "sgt_live_7d2a...",
  "refresh_token": "sgr_live_93ba...",
  "expires_in":    3600,
  "token_type":    "Bearer",
  "scope":         "reservations:read payments:write"
}

Available scopes

reservations:readRead reservations, guests, and folios

reservations:writeCreate, modify, and cancel reservations

rooms:readRead room types, inventory, and availability

rooms:writeUpdate rates, inventory, and room attributes

payments:readRead payment history and refunds

payments:writeCharge, refund, and void payments

webhooks:manageCreate, update, and delete webhook endpoints

reports:readExport revenue, occupancy, and production reports

RATE LIMITS

Fair, predictable, transparent

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. 429 responses tell you exactly when to retry.

Plan	Sustained	Burst	Daily cap
Starter	500 req/min	50 req/s	250k / day
Growth	1,000 req/min	100 req/s	500k / day
Scale	5,000 req/min	500 req/s	2.5M / day
Enterprise	Custom	Custom	Unlimited

example 429 response

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1744572300
Retry-After: 12

{
  "error": {
    "type": "rate_limit_exceeded",
    "code": "too_many_requests",
    "message": "Rate limit exceeded. Retry after 12 seconds."
  }
}

OFFICIAL SDKS

First-class clients for four stacks

Each SDK ships with type definitions, built-in retry with exponential backoff, automatic pagination, and helpers for webhook signature verification.

JavaScript / TypeScript

Node 18+, Bun, Deno, Cloudflare Workers

v3.4.1

npm install @swiftguest/sdk

swiftguest/swiftguest-node•Changelog

Python

Python 3.10+

v2.8.0

pip install swiftguest

swiftguest/swiftguest-python•Changelog

Go

Go 1.21+

v1.6.2

go get github.com/swiftguest/swiftguest-go

swiftguest/swiftguest-go•Changelog

PHP

PHP 8.1+

v1.4.0

composer require swiftguest/sdk

swiftguest/swiftguest-php•Changelog

API DESIGN

Predictable, composable, boring — in a good way

Our API follows the same contract across every resource. Learn it once and you already know how to use the next endpoint we ship.

Idempotent by design

POST requests accept an Idempotency-Key header. Retrying with the same key returns the same result — safe for network failures.

Cursor pagination

All list endpoints return next_cursor and prev_cursor. No offset — stable iteration even when data changes mid-scan.

Cursor-based timestamps

ISO 8601 everywhere. All timestamps returned in UTC. Convert locally based on property timezone metadata.

Consistent errors

Every error returns type, code, message, and param. No surprise status codes — 4xx for client errors, 5xx for server.

ENVIRONMENTS

Test safely before you go live

Every SwiftGuest account gets a sandbox with realistic test data — rooms, rate plans, and a seeded guest directory. Toggle between sandbox and live using a header, no separate credentials required.

Fully isolated sandbox environment
Seeded data mirrors a real 40-room hotel
Test card numbers for payment flows
Webhook event replay in sandbox
Rate limits identical to production

environment switching

# Live
https://api.swiftguest.com/v1

# Sandbox (same base URL, different header)
curl https://api.swiftguest.com/v1/reservations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "SwiftGuest-Environment: sandbox"

# Or set it in the SDK
const client = new SwiftGuest({
  apiKey: process.env.SWIFTGUEST_TOKEN,
  environment: "sandbox",
});

WHAT'S NEW

We ship, often

Follow every release, breaking change, and beta feature in the changelog. Subscribe by RSS or watch our GitHub to get notified the moment a new version lands.

Read the changelog System status

2026-04-01 • v1.8

Guest preferences endpoint

New /v1/guests/{id}/preferences resource for allergies, room preferences, and loyalty metadata.

2026-03-18 • v1.7

Cursor pagination on /payments

Offset pagination is deprecated. See the migration note.

2026-02-22 • v1.6

Housekeeping assignments API

Assign rooms to attendants and sync mobile checklists.

Found a bug? Missing an endpoint?

Open an issue on GitHub. We read every report, triage within 24 hours, and ship fixes in the next release. Feature requests welcome.

Open an issue developers@swiftguest.com Talk to us

Public roadmap

See what's shipping next

Community

Discord for developers

Office hours

Weekly API Q&A

Start building today

Create a sandbox account, grab a test token, and make your first API call in under a minute.

Create sandbox Webhooks reference