v1v2
← All Guides

Welcome to version 2 of the Avvail Guest Book API! This guide outlines the key improvements and changes you'll need to know when migrating from v1 to v2.

Targeting the v2 API

The v2 API is accessed using the /v2/ path prefix. All v2 endpoint paths start with /v2/ (e.g., /v2/availability, /v2/reservations, /v2/venues). The v1 API continues to be available at /v1/.

No additional version negotiation (such as Accept headers or query parameters) is required. The path prefix is the sole versioning mechanism.

Base URLs:

Environment Base URL
Production https://api.avvail.com/v2/
Sandbox https://sandbox.api.avvail.com/v2/

Example:

GET https://api.avvail.com/v2/venues
Authorization: Bearer <access_token>

Authentication tokens work across both v1 and v2 endpoints. You do not need separate credentials for v2.

What's New in v2

Real-Time Availability

V2 introduces a dynamic, real-time availability system that replaces v1's static inventory schedules.

Key Changes:

  • Availability Options: Query /v2/availability to receive server-generated booking options that reflect real-time capacity.
  • Dynamic Capacity: The system calculates available slots based on current reservations, active holds, seat allocations, entity capacity pools, and booking windows.
  • No Static Schedules: The /venues endpoint no longer returns fixed inventory schedules.

Benefits:

  • More accurate availability reflecting actual capacity.
  • Support for flexible party sizes and booking times.

Party Sizes

V1 enforced a hard cap of 4 on all party sizes. V2 removes this limit — party sizes are now venue-specific and dynamically determined by each venue's capacity configuration.

Discovering Supported Party Sizes:

  • The venue detail response includes a max_party_size field — the largest party size the venue offers for your entity's allocated inventory. Use this to set the upper bound of party-size selectors in your UI.
  • Query GET /v2/availability with the desired party_size. If the venue has available capacity for that size on the requested date, you'll receive booking options. If not, the response will contain the venue with empty options: "data": [{"venue_id": "...", "options": []}].
  • An empty availability response is not an error — it means there is no availability for the requested parameters.

Optional Hold Workflow

Protect your customers from booking conflicts with the optional hold mechanism.

How It Works:

  1. Query Availability: Get available options with GET /v2/availability
  2. Create Hold (Optional): Lock capacity for 10 minutes with POST /v2/holds
  3. Confirm Reservation: Complete the booking with POST /v2/reservations

Two Booking Paths:

  • Direct Booking: Skip the hold step for faster checkout (suitable for low-traffic scenarios).
  • Guaranteed Booking: Use holds to eliminate booking conflicts during high-demand periods.

Seating Area Support

Venues can now define multiple seating areas (e.g., "Patio", "Main Dining Room", "Bar").

  • Availability options include seating area information when applicable.
  • Guests can see and select their preferred area.
  • Venues can independently manage capacity, schedules, and availability per area.

Entity Management

Represent distinct booking channels — each with its own branding and access to program-level inventory, with optional capacity carveouts per entity.

Capabilities:

  • Create and manage entities via REST endpoints (POST /v2/entities, PATCH /v2/entities/{id}).
  • Allocate specific portions of venue inventory to each entity.
  • Availability and reservations are automatically scoped to each entity's allocations.

Use Cases:

  • White-label branding (custom logos, colors, and click-through URLs).
  • Separate inventory for different distribution channels.
  • Dedicated capacity for co-branded partnerships.

Reservation Modifications

V2 adds first-class support for changing existing reservations.

How to Modify:

  1. Query availability with modifying_reservation_id parameter (allows the system to account for existing capacity).
  2. Optionally create a hold for the new time/party size.
  3. Submit PATCH /v2/reservations/{id} with the new option_id or hold_id.

Atomic Swap: The server ensures guests are never left without a booking by coordinating the release of old capacity with confirmation of new capacity.

Simple Updates: Changes to special requests can be made directly without availability checks.

Reservation Reference Code

Reservation responses now include a reference_code field — a unique, human-friendly alphanumeric identifier suitable for displaying to guests. Use this instead of the UUID id when showing reservation details in guest-facing UIs.

Breaking Changes

API Convention: snake_case

All v2 endpoints, request bodies, and response fields use snake_case naming.

Examples:

  • createdAt → created_at
  • partySize → party_size
  • venueId → venue_id
  • specialRequests → special_requests

Entity Context

Entity context is resolved automatically on every v2 API request.

How It Works:

  • Your API credentials are linked to one or more entities, with a default entity configured.
  • All requests are scoped to your default entity automatically.
  • Multi-entity credentials can target a specific entity by including the X-Entity-Id: {entity-uuid} request header.
  • Reservation responses include entity_id (UUID) indicating which entity's allocation was used.
  • Entities retain external_id for your internal tracking needs.

Example:

GET /v2/reservations
Authorization: Bearer <access_token>
X-Entity-Id: 7f3c2b1a-8e4d-4f9c-a6b2-3d5e1a7c9f2b

When omitted, the request is scoped to the default entity associated with your API credentials.

Reservation Creation

Creating reservations now requires an availability option or hold.

V1 Approach (No Longer Supported):

POST /v1/reservations
{
  "date": "2024-12-01",
  "time": "19:30",
  "partySize": 4,
  "venueId": "venue-uuid",
  "guest": {...}
}

V2 Approach:

POST /v2/reservations
{
  "option_id": "opt_abc123xyz",
  "guest": {...}
}

Or with a hold:

POST /v2/reservations
{
  "hold_id": "hold_xyz789abc",
  "guest": {...}
}

Venue Response Structure

The venue endpoint no longer includes static inventory data for booking purposes, but adds transparency into your allocated inventory.

What Changed:

  • Removed: inventory object with schedules and slot configurations (use availability endpoint instead).
  • Removed: awards array with structured award data (award information now included as text in venue descriptions).
  • Retained: Venue details, operating hours, location, and metadata.
  • New: Optional seating_areas array when configured.
  • New: seat_commitments array showing contracted inventory with pricing, booking windows, and time ranges.
  • New: max_party_size integer indicating the largest party size the venue offers for your entity's inventory (see Party Sizes).
  • New: alt_text field on all image objects (venue photos, venue logos, entity logos) for accessibility.

Seat Commitments: The new seat_commitments field provides transparency into your contracted inventory, including:

  • Program identification (program_id, program_name) for multi-program venues.
  • Days of the week and time ranges for each commitment.
  • Number of seats contracted.
  • Pricing per seat (in subunits) and currency.
  • Booking window configuration (available_days_before, unavailable_days_before).

To Get Availability: Query /v2/availability?venue_id={venue_id}&date={date}&party_size={party_size}. The response uses a venue-grouped format — see Multi-Venue Availability for the full response shape and multi-venue query options.

New OAuth Scopes

V2 introduces granular permissions for new features.

New Scopes:

  • availability:read — Query real-time availability options
  • markets:read — List geographic markets for multi-venue search
  • entities:create — Create entities
  • entities:read — Read entity data
  • entities:update — Update entities
  • entities:upload_logo — Upload entity logos
  • holds:create — Create temporary capacity holds
  • holds:delete — Release capacity holds early
  • reservations:update — Modify existing reservations

Unchanged Scopes:

  • reservations:create, reservations:read, reservations:cancel, venues:read

Backward Compatibility

  • V1 remains available during the transition period.
  • V1 will not receive new features (seating areas, modifications, entities).
  • No breaking changes to v1 — your existing integration continues to work.

Quick Reference

Common Operations

Query Availability (single venue):

GET /v2/availability?venue_id={venue_id}&date=2026-04-01&party_size=4

Query Availability (multi-venue / market):

GET /v2/availability?market_id={market_id}&date=2026-04-01&party_size=4

See Multi-Venue Availability for all query modes.

Create Hold:

POST /v2/holds

{
  "option_id": "opt_abc123xyz"
}

Create Reservation:

POST /v2/reservations

{
  "hold_id": "hold_xyz789abc",
  "guest": {
    "email": "guest@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "mobile_number": "+15555555555"
  },
  "special_requests": "Window seat preferred"
}

Modify Reservation:

GET /v2/availability?venue_id={venue_id}&date=2026-04-01&party_size=6&modifying_reservation_id={reservation_id}

POST /v2/holds
{
  "option_id": "opt_new123xyz",
  "modifying_reservation_id": "{reservation_id}"
}

PATCH /v2/reservations/{reservation_id}
{
  "hold_id": "hold_new789abc",
  "special_requests": "Window seat preferred"
}

Cancel Reservation:

POST /v2/reservations/{reservation_id}/cancel

Support

Questions? Contact us at support@avvail.com.