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 has been retired — /v1/ endpoints no longer accept requests, so v2 is the only live API.

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

Base URLs:

Example:

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

Your existing API credentials work for v2 — no separate credentials are required.

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 — see the Seat Allocations guide for viewing and managing your allocations.
• 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.

Added Since 2.0.0

These endpoints and concepts shipped in v2 minor releases after the initial 2.0.0 cutover. New integrations should adopt them from the start; existing v1 → v2 migrations can pick them up incrementally. See the Changelog for the per-version detail.

2.2.0:

• Commitments — GET /v2/commitments, GET /v2/commitments/{id}, PUT /v2/commitments. View and manage your commitments, and replace your assigned commitments in one call. Scopes: commitments:read, commitments:update. See the Seat Allocations guide. Supersedes the now-deprecated seat_commitments block on GET /v2/venues/{id}.
• Entity program assignments — POST /v2/entities now accepts a programs[] set (each entry with unallocated_seat_access) and default_program_id; PUT /v2/entities/{id}/programs replaces the entity's assigned programs in one call; PATCH /v2/entities/{id} rejects programs[] to keep replacement explicit. See the API reference for the full three-operation overview.
• Identity introspection — GET /v2/identities/me, GET /v2/identities/me/delegates, GET /v2/identities/me/delegates/{id}. Self-introspection for the calling JWT (effective status, default entity, associated entity ids, and any delegated identities you manage). No scope required. See the Authentication guide.
• org_id self-discovery — the Entity schema now exposes org_id, the organization identifier you pass as the organization parameter when requesting an organization-bound access token. Self-discoverable via GET /v2/entities; replaces the previous "ask support" workflow.

2.1.0:

• Localization — optional locale on POST /v2/reservations and default_locale on entities control the language of transactional emails. See the Localization guide.

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 should target a specific entity by requesting an organization-bound access token — include the organization parameter in your POST /oauth/token request and the returned token carries an org_id JWT claim that binds the request to the correct entity.
• The legacy X-Entity-Id: {entity-uuid} request header is still honored when the token has no org_id claim, but it is deprecated. New integrations should use organization-bound tokens from the start; existing integrations continue to work and will receive adequate notice before any removal. See Requesting an Organization-Bound Token in the Authentication guide for setup steps.
• Reservation responses include entity_id (UUID) indicating which entity's allocation was used.
• Entities retain external_id for your internal tracking needs.

Recommended (org_id-bound token):

GET /v2/reservations
Authorization: Bearer <access_token_with_org_id>

Deprecated (X-Entity-Id header):

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

When neither mechanism resolves an entity, the request is scoped to the default entity associated with your API credentials. See the Authentication guide for the full resolution order.

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, then deprecated in 2.2.0: seat_commitments array showing contracted inventory with pricing, booking windows, and time ranges. Use GET /v2/commitments?venue_id=<id> for the same per-venue view scoped to your entity; the nested block remains in place with no behavior change.
• 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: (deprecated in 2.2.0 — use GET /v2/commitments?venue_id=<id> instead) The seat_commitments field on GET /v2/venues/{id} 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

v1 Retirement

• The v1 API has been retired and no longer accepts requests.
• v1 was frozen at its final feature set and never gained the capabilities introduced in v2.
• The v1 reference remains published for historical context, but all new and existing integrations must target v2.

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.