Avvail | Advanced Usage

This guide covers more complex features and best practices to help you get the most out of the Avvail Guest Book API.

Query Parameters & Filtering

When making requests to the API, you can use query parameter modifiers to filter data based on specific conditions:

Modifier	Meaning	Example Usage
`[eq]`	Equal to (default if no modifier is specified)	`status[eq]=completed`
`[neq]`	Not equal to	`status[neq]=pending`
`[in]`	In a list of values	`status[in]=pending,confirmed`
`[nin]`	Not in a list of values	`status[nin]=canceled,no_show`
`[gte]`	Greater than or equal to	`date[gte]=2025-01-01`
`[lte]`	Less than or equal to	`date[lte]=2025-01-01`

Refer to the API Reference for endpoint-specific supported attributes and modifiers.

Example

Filter reservations by status and date range:

GET /v2/reservations?status[in]=pending,confirmed&date[gte]=2025-03-01&date[lte]=2025-03-31&created_at[gte]=2025-01-01T00:00:00Z

Pagination

Use page and limit to paginate large result sets:

GET /v2/reservations?page=2&limit=20

The response includes a pagination object with the following fields:

Field	Description
`current_page`	Current page number
`total_pages`	Total number of pages
`total_items`	Total number of records
`items_per_page`	Number of records per page

Rate Limiting

Each response includes rate-limit headers:

Header	Description
`X-RateLimit-Limit`	Rate limit for the current window
`X-RateLimit-Remaining`	Remaining requests in the current window
`X-RateLimit-Reset`	Unix timestamp for the next reset

If you exceed the limit, you'll receive 429 Too Many Requests. Implement backoff or throttling to avoid disruptions.

By default, each client can make up to 1,000 requests per minute, and rate limits reset every 60 seconds. If your integration requires higher limits, please contact us to discuss adjustments.

Multi-Venue Availability

For multi-venue search, market-scoped queries, and date range availability, see the dedicated Multi-Venue Availability guide.

Entity Context

Entity context is resolved automatically on every v2 API request. 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 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 the X-Entity-Id header is omitted, the request is scoped to the default entity associated with your API credentials.

Best Practices

Validate Before Sending: Ensure UUIDs, dates, and other fields are formatted properly to avoid 400 or 422 errors.
Token Reuse: Store and reuse tokens until they expire. Avoid requesting a new token for every call.
Monitor Rate Limits: Keep an eye on X-RateLimit-Remaining to prevent hitting 429 errors.
Stay Updated: We may add new fields or endpoints over time. Watch for release notes and announcements.