Quickstart

This walkthrough runs the entire booking lifecycle against the live API, the same path a custom booking engine or guest app follows. By the end you will have searched availability, priced a stay, registered a guest, held a room, confirmed a paid reservation, read the folio, and earned loyalty points.

What you need

An API key (see Authentication) with these scopes: availability:read, guests:write, reservations:write, folio:write, and loyalty:read. Set it once for the shell:

export VRDN_KEY="vrdn_live_xxxxxxxxxxxxxxxxxxxx"
export VRDN_BASE="https://veridien.app/api/v1"

1. Confirm the key works

curl "$VRDN_BASE/me" -H "Authorization: Bearer $VRDN_KEY"

{
  "property_id": "p_8f2a1c",
  "scopes": ["availability:read", "guests:write", "reservations:write", "folio:write", "loyalty:read"],
  "request_id": "req_a1b2c3d4e5"
}

2. Search availability

Find which room types are bookable for the dates and party.

curl "$VRDN_BASE/availability?check_in=2026-08-01&check_out=2026-08-04&adults=2&children=0" \
  -H "Authorization: Bearer $VRDN_KEY"

{
  "check_in": "2026-08-01",
  "check_out": "2026-08-04",
  "data": [
    { "room_type_id": "rt_deluxe", "name": "Deluxe Ocean Villa", "max_occupancy": 3, "available": 4, "base_rate": "420.00", "currency": "USD" }
  ]
}

3. Price the stay with rates

/rates returns each room type's visible rate plans with a per-night breakdown. Rate-plan visibility rules (local-only, promo-gated, loyalty-tier) are enforced server-side; pass guest_id or promo_code to unlock gated rates.

curl "$VRDN_BASE/rates?check_in=2026-08-01&check_out=2026-08-04&adults=2" \
  -H "Authorization: Bearer $VRDN_KEY"

{
  "check_in": "2026-08-01",
  "check_out": "2026-08-04",
  "data": [
    {
      "room_type_id": "rt_deluxe",
      "name": "Deluxe Ocean Villa",
      "max_occupancy": 3,
      "amenities": ["Ocean view", "Private deck"],
      "photos": ["https://cdn.veridien.app/p_8f2a1c/deluxe-1.jpg"],
      "rate_plans": [
        {
          "rate_plan_id": "rp_flex",
          "name": "Flexible",
          "currency": "USD",
          "total": "1260.00",
          "nightly_rates": [
            { "date": "2026-08-01", "day_of_week": 6, "rate": "420.00", "source": "base_price" },
            { "date": "2026-08-02", "day_of_week": 0, "rate": "420.00", "source": "base_price" },
            { "date": "2026-08-03", "day_of_week": 1, "rate": "420.00", "source": "base_price" }
          ]
        }
      ]
    }
  ]
}

4. Register or link the guest

Reservations belong to a guest. POST /guests finds an existing guest by email or creates one — idempotent on email, so it is safe to call on every checkout.

curl -X POST "$VRDN_BASE/guests" \
  -H "Authorization: Bearer $VRDN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "first_name": "Ada", "last_name": "Lovelace", "nationality": "GB" }'

{ "guest_id": "G7K2P9QX", "created": true }

5. Hold the room

Create a soft hold. This reserves inventory for 15 minutes by creating a tentative reservation, prices the stay (room nights + taxes onto a folio), and returns a reservation_id to confirm.

Use an Idempotency-Key

Always send an Idempotency-Key on holds and confirmations so a network retry never creates a duplicate. See Conventions.

curl -X POST "$VRDN_BASE/holds" \
  -H "Authorization: Bearer $VRDN_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1d2c9a-8b3e-4a17-9c2f-1e5b7d0a4c83" \
  -d '{
    "room_type_id": "rt_deluxe",
    "rate_plan_id": "rp_flex",
    "check_in": "2026-08-01",
    "check_out": "2026-08-04",
    "guest_id": "G7K2P9QX",
    "adults": 2
  }'

{
  "reservation_id": "RES4K9PA",
  "folio_id": "fl_2b7c",
  "hold_expires_at": "2026-06-19T08:45:00.000Z",
  "total": "1260.00",
  "currency": "USD",
  "status": "tentative"
}

6. Confirm with payment

Take payment in your own flow, then confirm the hold with a payment_reference. Veridien marks the reservation confirmed, records the payment on the folio, and (for USD stays) awards loyalty points.

curl -X POST "$VRDN_BASE/holds/RES4K9PA/confirm" \
  -H "Authorization: Bearer $VRDN_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9a2e7c10-4b3f-4d28-8c1f-2e6b8d0a5d94" \
  -d '{ "payment_reference": "pay_abc123" }'

{
  "reservation_id": "RES4K9PA",
  "status": "confirmed",
  "check_in_date": "2026-08-01",
  "check_out_date": "2026-08-04",
  "currency": "USD",
  "folio_balance": "0.00",
  "already_confirmed": false
}

Confirmation is idempotent: replaying the same payment_reference returns "already_confirmed": true without charging again.

7. Post an extra charge (optional)

Add anything to the guest's folio during the stay — a spa treatment, a restaurant order, a minibar item.

curl -X POST "$VRDN_BASE/reservations/RES4K9PA/folio/charges" \
  -H "Authorization: Bearer $VRDN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Spa treatment", "amount": "120.00", "category": "service" }'

{ "line_item_id": "li_5d8e", "folio_balance": "120.00" }

8. Read the folio and loyalty

curl "$VRDN_BASE/reservations/RES4K9PA/folio" -H "Authorization: Bearer $VRDN_KEY"
curl "$VRDN_BASE/guests/G7K2P9QX/loyalty" -H "Authorization: Bearer $VRDN_KEY"

That is the full loop. From here, explore the resource references for every field and option:

The same flow in JavaScript

const BASE = "https://veridien.app/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.VRDN_KEY}`,
  "Content-Type": "application/json",
};

async function api(path: string, init?: RequestInit) {
  const res = await fetch(`${BASE}${path}`, { ...init, headers: { ...headers, ...init?.headers } });
  const body = await res.json();
  if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
  return body;
}

// 1. Register the guest
const { guest_id } = await api("/guests", {
  method: "POST",
  body: JSON.stringify({ email: "[email protected]", first_name: "Ada", last_name: "Lovelace" }),
});

// 2. Hold a room
const hold = await api("/holds", {
  method: "POST",
  headers: { "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({
    room_type_id: "rt_deluxe",
    rate_plan_id: "rp_flex",
    check_in: "2026-08-01",
    check_out: "2026-08-04",
    guest_id,
    adults: 2,
  }),
});

// 3. Confirm after payment
const reservation = await api(`/holds/${hold.reservation_id}/confirm`, {
  method: "POST",
  headers: { "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({ payment_reference: "pay_abc123" }),
});

console.log(reservation.status); // "confirmed"

On this page