Docs/Documentation/Learn

Create Booking

Create reservations programmatically for direct bookings, owner blocks, maintenance holds, or imports from external systems.

When to use this endpoint

Accept direct bookings from your own website or booking engine
Create owner blocks to hold dates for personal use
Block dates for maintenance or renovation work
Import existing reservations from an external system during migration

Idempotency recommended

Pass an Idempotency-Key header to safely retry requests without creating duplicate reservations. See Idempotency for details.

Create a reservation

POST/v1/reservations

curl -X POST "https://api.repull.dev/v1/reservations" \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-booking-id-001" \
  -d '{
    "propertyId": "123",
    "checkIn": "2026-07-10",
    "checkOut": "2026-07-15",
    "primaryGuest": {
      "firstName": "Sarah",
      "lastName": "Mitchell",
      "email": "sarah@example.com",
      "phone": "+1-555-0123"
    },
    "occupancy": { "adults": 2, "children": 1, "infants": 0, "pets": 0 },
    "financials": { "totalPrice": 1250, "currency": "USD" },
    "source": "DIRECT"
  }'

Body parameters

propertyIdstringRequired

ID of the property to book.

checkIndateRequired

Check-in date. Format: YYYY-MM-DD.

checkOutdateRequired

Check-out date. Format: YYYY-MM-DD.

primaryGuestobjectRequired

Guest who is making the booking.

firstName (required), lastName, email, phone

occupancyobject

Number of guests by category.

adults children infants pets

financialsobject

Pricing for the reservation.

totalPrice currency (ISO 4217)

sourcestring

Where the booking originated.

DIRECT MANUAL AIRBNB BOOKING_COM VRBO

Response format

Returns the newly created reservation with a system-generated confirmation code.

{
  "data": {
    "id": "789",
    "propertyId": "123",
    "status": "CONFIRMED",
    "source": "DIRECT",
    "confirmationCode": "RPL-A7X92K",
    "checkIn": "2026-07-10",
    "checkOut": "2026-07-15",
    "primaryGuest": {
      "firstName": "Sarah",
      "lastName": "Mitchell",
      "email": "sarah@example.com",
      "phone": "+1-555-0123"
    },
    "occupancy": {
      "adults": 2,
      "children": 1,
      "infants": 0,
      "pets": 0
    },
    "financials": {
      "totalPrice": 1250,
      "currency": "USD",
      "paymentStatus": "pending",
      "breakdown": {
        "basePrice": 1100,
        "cleaningFee": 100,
        "fees": [{ "type": "SERVICE_FEE", "amount": 50 }],
        "taxes": [],
        "discounts": []
      }
    },
    "bookedAt": "2026-06-20T14:30:00Z"
  }
}

Response fields

idstring

Unique reservation identifier.

propertyIdstring

ID of the booked property.

statusstring

Initial status, typically CONFIRMED for direct bookings.

sourcestring

Booking source passed in the request.

confirmationCodestring

System-generated confirmation code (e.g. RPL-A7X92K).

checkInstring

Check-in date (YYYY-MM-DD).

checkOutstring

Check-out date (YYYY-MM-DD).

primaryGuestobject

Guest details as provided.

occupancyobject

Number of guests by category.

financialsobject

Complete pricing breakdown.

bookedAtstring

ISO 8601 timestamp when the reservation was created.

Common examples

Owner block (no guest details)

curl -X POST "https://api.repull.dev/v1/reservations" \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "propertyId": "123",
    "checkIn": "2026-08-01",
    "checkOut": "2026-08-10",
    "primaryGuest": { "firstName": "Owner" },
    "source": "MANUAL"
  }'

Maintenance hold

curl -X POST "https://api.repull.dev/v1/reservations" \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "propertyId": "123",
    "checkIn": "2026-09-15",
    "checkOut": "2026-09-20",
    "primaryGuest": { "firstName": "Maintenance" },
    "source": "MANUAL"
  }'

API Reference

See the complete Reservations API Reference for all endpoints including list, update, and cancel.

Previous← Get Reservations NextUpdate a Reservation →