AI Hotel Intelligence API

Technical Docs Decision Engine Hotels B2B
Operated by Spyface Tech Company, LLC • Support: hello@spyface.com

1) Overview

Hotels are not “search” problems. They are decision problems: the same user sees 200+ “available” offers, but only 3–8 are truly optimal given intent, cancellation terms, hidden costs, payment policy, and operational risk.

2) Quickstart

1. Generate an API key in your Spyface dashboard.
2. POST your hotel offers to /v1/hotels/decision
3. Render results using rank.position and scores

3) Authentication

Use Bearer token authentication.

Authorization: Bearer YOUR_SPYFACE_API_KEY

4) Endpoints

5) Data Model

5.1 Decision Request

{
  "request_id": "req_20260125_9f3a",
  "search": {
    "check_in": "2026-03-12",
    "check_out": "2026-03-15",
    "adults": 2,
    "children": 0,
    "city_code": "IST",
    "currency": "USD"
  },
  "user": {
    "user_id": "u_123",
    "segment": "business",
    "loyalty_tier": "silver"
  },
  "context": {
    "channel": "web",
    "device": "desktop",
    "locale": "en-US",
    "market": "US"
  },
  "offers": [
    {
      "offer_id": "o_001",
      "hotel_id": "h_7781",
      "name": "Example Hotel",
      "geo": {"lat": 41.0082, "lng": 28.9784},
      "stars": 4,
      "review_score": 8.6,
      "room": {"type": "DELUXE", "beds": 1},
      "board": "BREAKFAST_INCLUDED",
      "price": {"total": 420.50, "taxes_included": true, "currency": "USD"},
      "policies": {
        "cancellation": {"type": "REFUNDABLE_UNTIL", "deadline": "2026-03-10T23:59:59Z"},
        "payment": {"type": "GUARANTEE", "card_required": true}
      },
      "supplier": {"name": "supplier_x", "rate_plan": "rp_12"}
    }
  ]
}

5.2 Decision Response

{
  "request_id": "req_20260125_9f3a",
  "generated_at": "2026-01-25T12:00:00Z",
  "results": [
    {
      "offer_id": "o_001",
      "rank": {"position": 1, "out_of": 200},
      "scores": {
        "conversion": 0.71,
        "margin": 0.62,
        "policy_fit": 0.88,
        "price_integrity": 0.93,
        "availability_confidence": 0.86,
        "risk": 0.12
      },
      "explanations": [
        {"code":"POLICY_MATCH", "detail":"Refundable until 48h aligns with business segment"},
        {"code":"PRICE_STABLE", "detail":"Low volatility vs market baseline"},
        {"code":"HIGH_BOOKABILITY", "detail":"Supplier reliability high for these dates"}
      ],
      "actions": {
        "badges": ["Best value", "Flexible cancellation"],
        "recommendation": "PIN_TO_TOP"
      }
    }
  ]
}

6) AI Decision Layer (Real Specs)

Spyface uses four independent models (not one “mystery AI”) and a deterministic optimizer:

7) Ranking & Optimization (What makes it superior)

Spyface ranking is not “sort by score”. It’s a constrained optimization problem:

• Objective: maximize expected value = (conversion × margin) − risk_penalty − integrity_penalty
• Constraints: supplier mix, price bands, policy requirements, inventory classes, geography, fairness
• Diversity: ensure top results aren’t all the same neighborhood / price tier

// Example objective (conceptual)
EV(offer) =
  w1 * P(book) +
  w2 * MarginScore -
  w3 * RiskScore -
  w4 * (1 - AvailabilityConfidence) -
  w5 * (1 - PriceIntegrity)

8) Price & Availability Integrity

The most expensive failure in hotels is not “no conversion”. It’s conversion → checkout → fail. That burns trust, increases support costs, and kills LTV.

9) Risk (Fraud, chargeback, disputes)

Hotels create risk differently than flights: disputes often come from policy misunderstanding, non-refundable traps, and supplier inconsistency.

• Risk score per offer + per user context
• Policy-fit guardrail to prevent mismatch
• Optional: “high-risk checkout” verification flows

10) Observability & SLAs

11) Code Examples

11.1 cURL — Decision

curl -X POST "https://api.spyface.com/v1/hotels/decision" \
  -H "Authorization: Bearer YOUR_SPYFACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @decision-request.json

11.2 Node.js — Decision

import fetch from "node-fetch";

const res = await fetch("https://api.spyface.com/v1/hotels/decision", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SPYFACE_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});

if (!res.ok) {
  const err = await res.text();
  throw new Error(`Spyface API error: ${res.status} ${err}`);
}

const data = await res.json();
console.log(data.results[0]);

11.3 Python — Decision

import os, requests

resp = requests.post(
  "https://api.spyface.com/v1/hotels/decision",
  headers={
    "Authorization": f"Bearer {os.environ['SPYFACE_API_KEY']}",
    "Content-Type": "application/json",
  },
  json=payload,
  timeout=10
)

resp.raise_for_status()
data = resp.json()
print(data["results"][0]["scores"])

11.4 Event Streaming — Behavior Signals

Send events to improve personalization and calibration. This is optional but recommended.

{
  "request_id": "req_20260125_9f3a",
  "events": [
    {"type":"VIEW_OFFER", "offer_id":"o_001", "ts":"2026-01-25T12:00:02Z"},
    {"type":"SHORTLIST", "offer_id":"o_001", "ts":"2026-01-25T12:01:11Z"},
    {"type":"CHECKOUT_START", "offer_id":"o_001", "ts":"2026-01-25T12:03:44Z"}
  ]
}

12) Errors

13) Security

• Encrypt in transit (TLS). Do not send raw card numbers to Spyface.
• Send only what’s needed: offers, policy fields, context; avoid unnecessary PII.
• Optional: sign requests with HMAC (available for enterprise plans).