Bookings

Bookings

Retrieve bookings in a given date range. Results are scoped to your permitted units and ordered by reservation_start (asc), then booking_date (asc).

• Method: GET

• Endpoint: https://api.okup.ai/data/bookings

• Auth: header X-API-Key: YOUR_API_KEY (required)

Query parameters

• from (string, optional): inclusive start date filter on reservation_start (format YYYY-MM-DD)

• to (string, optional): inclusive end date filter on reservation_start (format YYYY-MM-DD)

• unit (string, optional): case-insensitive substring match on the unit’s friendly_name

• limit (integer, optional): page size; default 100, max 1000

• offset (integer, optional): items to skip; default 0

Booking item fields

All fields may be null if unknown. Dates are ISO strings; monetary values are numbers (floats).

Field	Type	Example	Description
internal_booking_id	string	Internal immutable identifier (UUID-like).	null
booking_id	string	Channel/source booking identifier.	null
platform	string	Source platform.	null
friendly_name	string	Human-readable unit name.	null
listing_id	string	Listing identifier on the platform.	null
booking_date	string	When the booking was made (ISO date/datetime).	null
reservation_start	string	Check-in date (ISO date).	null
reservation_end	string	Check-out date (ISO date).	null
status	string	Current booking status.	null
guest_name	string	Guest full name.	null
email	string	Guest email.	null
phone	string	Guest phone (as provided).	null
guest_origin	string	Raw channel/source label if present.	null
guest_origin_gpt	string	Normalized/derived origin categorization.	null
adults	number	Number of adult guests.	null
children	number	Number of child guests.	null
nights_price	number	Accommodation subtotal for nights.	null
cleaning	number	Cleaning fee component.	null
city_tax_platform	number	City/tourist tax as reported by platform.	null
commission_host	number	Host commission/fee amount.	null
currency	string	ISO currency code.	null
fx_rate_to_eur	number	FX rate applied to convert to EUR.	null
fx_fixed_at	string	Timestamp when FX rate was fixed (ISO datetime).	null
fx_source	string	FX source/provider label.	null

Notes:

• Dates and timestamps are returned as ISO strings.

• Decimal amounts are returned as JSON numbers (floats).

• Fields may be null if not applicable or unknown.

Basic example

JavaScript

// Server-side (Node 18+). Don’t expose API keys in the browser.
const BASE_URL = 'https://api.okup.ai';
const API_KEY = process.env.OKUPAI_API_KEY;

const res = await fetch(`${BASE_URL}/data/bookings?from=2025-01-01&to=2025-01-31&limit=10`, {
  headers: { 'X-API-Key': API_KEY },
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
/** @type {{ total:number, limit:number, offset:number, items:any[] }} */
const data = await res.json();
console.log(data);

Python

cURL

Example response (truncated):

{
  "total": 42,
  "limit": 10,
  "offset": 0,
  "items": [
    {
      "internal_booking_id": "9a2a6b0f-3a3d-4c1e-8b8b-12f3f9a7f001",
      "booking_id": "123456789",
      "platform": "airbnb",
      "friendly_name": "Main Apartment",
      "listing_id": "987654",
      "booking_date": "2025-01-02",
      "reservation_start": "2025-01-10",
      "reservation_end": "2025-01-12",
      "status": "confirmed",
      "guest_name": "Jane Doe",
      "email": "[email protected]",
      "phone": "[phone]",
      "guest_origin": "app",
      "guest_origin_gpt": "direct",
      "adults": 2,
      "children": 0,
      "nights_price": 215.0,
      "cleaning": 35.0,
      "city_tax_platform": 4.8,
      "commission_host": 21.5,
      "currency": "EUR",
      "fx_rate_to_eur": 1.0,
      "fx_fixed_at": "2025-01-02T08:30:00Z",
      "fx_source": "ECB"
    }
  ]
}

Filtering by unit name

Use unit to match friendly_name (case-insensitive substring).

JavaScript

const BASE_URL = 'https://api.okup.ai';
const API_KEY = process.env.OKUPAI_API_KEY;
const unit = encodeURIComponent('Apartment');

const res = await fetch(`${BASE_URL}/data/bookings?from=2025-01-01&to=2025-01-31&unit=${unit}`, {
  headers: { 'X-API-Key': API_KEY },
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
console.log(await res.json());

Python

cURL

Error codes

• 401 Unauthorized — missing X-API-Key header

• 403 Forbidden — invalid key or verification failed

• Ensure your API key is valid and sent on every request.