> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elivaas.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Introduction
> Integrate the Elivaas Distribution API to power property search, availability, and bookings on your platform.
# Elivaas Distribution API
The Elivaas Distribution API enables channel partners to programmatically search properties, retrieve real-time availability and pricing, and create confirmed bookings. It is a RESTful API that accepts and returns JSON over HTTPS.
Go from zero to your first booking in four steps.
Explore the full endpoint reference with request and response schemas.
Reach the integrations team at [api@elivaas.com](mailto:api@elivaas.com).
***
## Authentication
All requests are authenticated with two headers issued by the Elivaas team during onboarding.
| Header | Type | Description |
| ------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `Api-Key` | string | A secret key that identifies your application. Treat it like a password — transmit it only over HTTPS and never expose it in client-side code. |
| `Channel-Id` | string | Identifies your distribution channel. Determines which properties, rate plans, and promotions are accessible. |
```bash theme={null}
curl -X GET "https://sandbox.elivaas.com/v1/cities" \
-H "Api-Key: YOUR_API_KEY" \
-H "Channel-Id: YOUR_CHANNEL_ID"
```
Requests missing either header will receive a `401 Unauthorized` response.
***
## Base URLs
| Environment | Base URL | Description |
| -------------- | ----------------------------- | -------------------------------------------------------------------------------- |
| **Sandbox** | `https://sandbox.elivaas.com` | Isolated environment for development and testing. No real inventory is affected. |
| **Production** | `https://api.elivaas.com/api` | Live environment with real-time inventory. Bookings created here are fulfilled. |
Complete your integration against Sandbox before switching to Production. Both environments share the same API contract — only the base URL changes.
***
## Quick Start
The core booking flow requires four steps. Each step produces a value consumed by the next.
```
Fetch Cities ──▶ Search Properties & Rates ──▶ Get a Quote ──▶ Create Booking
(slugs) (browse) (lock pricing) (confirm)
```
***
### 1. Fetch Cities
Before you can search properties by location, you need the list of available cities and states. This call returns slug values that are required as the `city` parameter in the Discovery API.
```bash theme={null}
curl -X GET "https://sandbox.elivaas.com/v1/cities" \
-H "Api-Key: YOUR_API_KEY" \
-H "Channel-Id: YOUR_CHANNEL_ID"
```
**Response:**
```json theme={null}
[
{
"name": "Goa",
"displayName": "Goa",
"slug": "stategoa",
"type": "STATE",
"numberOfProperties": null
},
{
"name": "North Goa",
"displayName": "North Goa, Goa",
"slug": "citynorth-goa",
"type": "CITY",
"numberOfProperties": null
},
{
"name": "Shimla",
"displayName": "Shimla, Himachal Pradesh",
"slug": "cityshimla",
"type": "CITY",
"numberOfProperties": null
}
]
```
**How to use:**
* Display `displayName` in your location dropdown or filter UI.
* Store the `slug` value — pass it as the `city` parameter in Step 2.
* `STATE` slugs (e.g., `stategoa`) return properties across all cities in that state.
* `CITY` slugs (e.g., `citynorth-goa`) return properties in that specific city only.
Cache this response. The cities list changes infrequently — fetch it once on app load and refresh periodically.
***
### 2. Search Properties & Rates
Use the Discovery API to retrieve a paginated list of available properties with calculated pricing. Pass the `slug` from Step 1 as the `city` parameter.
```bash theme={null}
curl -X GET "https://sandbox.elivaas.com/v1/properties/rates\
?checkinDate=2025-08-01\
&checkoutDate=2025-08-05\
&adults=2\
&children=1\
&city=stategoa\
&page=0\
&pageSize=10" \
-H "Api-Key: YOUR_API_KEY" \
-H "Channel-Id: YOUR_CHANNEL_ID"
```
**Response** — a paginated list of property cards, each containing one or more `quotes` (rate plan options):
```json theme={null}
{
"list": [
{
"id": "prop_456",
"name": "Luxury Beach Villa",
"soldOut": false,
"quotes": [
{
"propertyId": "prop_456",
"ratePlanId": "rp_123",
"ratePlanCode": "european-plan",
"ratePlanName": "Room Only",
"propertyName": "Luxury Beach Villa",
"checkinDate": "2025-08-01",
"checkoutDate": "2025-08-05",
"numberOfNights": 4,
"adults": 2,
"children": 1,
"numberOfGuests": 3,
"originalNetAmountBeforeTax": 6000,
"originalNetAmountAfterTax": 7080,
"netAmountBeforeTax": 6000,
"netAmountAfterTax": 7080,
"netPerNightAmountBeforeTax": 1500,
"netPerNightAmountAfterTax": 1770,
"gstAmount": 1080,
"securityDeposit": 1000,
"soldOut": false
}
]
}
],
"currentPage": 0,
"pageSize": 10,
"totalElementsCount": 25,
"pagesCount": 3,
"hasNext": true,
"hasPrevious": false
}
```
**Key response fields:**
| Field | Purpose |
| ------------------------------------ | -------------------------------------------------------------------------- |
| `quotes[].ratePlanCode` | Identifies the rate plan. Required in Step 3 to generate a quote. |
| `quotes[].netAmountAfterTax` | Total stay cost inclusive of tax. Display as the headline price. |
| `quotes[].netPerNightAmountAfterTax` | Per-night price inclusive of tax. |
| `quotes[].originalNetAmountAfterTax` | Price before discounts. Show as strike-through when a discount is applied. |
| `soldOut` | When `true`, the property has no availability for the requested dates. |
**Supported query parameters:**
| Parameter | Type | Default | Description |
| -------------- | ------- | ------- | ----------------------------------------------------------- |
| `city` | string | — | **City slug from Step 1.** Required for location filtering. |
| `checkinDate` | date | — | Check-in date (`YYYY-MM-DD`). |
| `checkoutDate` | date | — | Check-out date (`YYYY-MM-DD`). |
| `adults` | integer | `1` | Number of adult guests. |
| `children` | integer | `0` | Number of child guests. |
| `propertyId` | string | — | Retrieve rates for a single property. |
| `keyword` | string | — | Free-text search across property names. |
| `couponCode` | string | — | Apply a coupon to preview discounted pricing. |
| `bedroom` | integer | — | Filter by number of bedrooms. |
| `page` | integer | `0` | Zero-based page index. |
| `pageSize` | integer | `50` | Results per page. |
For the full response schema including property details, images, amenities, FAQs, and all quote fields, see the [Discovery API reference](/api-reference/property-rates/property-rates).
***
### 3. Get a Quote
When the user selects a property and rate plan, request a **quote** by adding the `ratePlanCode` parameter. The response returns an `id` — a token that locks in the pricing for booking.
```bash theme={null}
curl -X GET "https://sandbox.elivaas.com/v1/properties/rates\
?propertyId=prop_456\
&checkinDate=2025-08-01\
&checkoutDate=2025-08-05\
&ratePlanCode=european-plan\
&adults=2\
&children=1\
&quantity=1" \
-H "Api-Key: YOUR_API_KEY" \
-H "Channel-Id: YOUR_CHANNEL_ID"
```
**Response** — includes `id` and final pricing breakdown:
```json theme={null}
{
"list": [
{
"id": "prop_456",
"soldOut": false,
"quotes": [
{
"id": "quote_abc123",
"propertyId": "prop_456",
"ratePlanId": "rp_123",
"ratePlanCode": "european-plan",
"ratePlanName": "Room Only",
"checkinDate": "2025-08-01",
"checkoutDate": "2025-08-05",
"numberOfNights": 4,
"adults": 2,
"children": 1,
"quantity": 1,
"netAmountBeforeTax": 6000,
"netAmountAfterTax": 7080,
"gstAmount": 1080,
"securityDeposit": 1000
}
]
}
]
}
```
Present the pricing summary to the user before confirmation:
| Display Label | Field |
| ---------------- | ----------------------- |
| Rate Plan | `ratePlanName` |
| Nights | `numberOfNights` |
| Subtotal | `netAmountBeforeTax` |
| Tax (GST) | `gstAmount` |
| **Total** | **`netAmountAfterTax`** |
| Security Deposit | `securityDeposit` |
Persist the `id` — it is required (passed as `quoteId`) to create the booking in the next step.
***
### 4. Create a Booking
Submit the `quoteId` along with guest details to confirm the reservation.
```bash theme={null}
curl -X POST "https://sandbox.elivaas.com/v2/bookings" \
-H "Api-Key: YOUR_API_KEY" \
-H "Channel-Id: YOUR_CHANNEL_ID" \
-H "Content-Type: application/json" \
-d '{
"quoteId": "quote_abc123",
"bookingId": "your_unique_booking_id",
"bookingStatus": "CONFIRMED",
"guest": {
"email": "guest@example.com",
"phone": "+911234567890",
"firstName": "John",
"lastName": "Doe"
}
}'
```
**Request body:**
| Field | Type | Required | Constraints |
| ----------------- | ------ | -------- | ---------------------------------------------------- |
| `quoteId` | string | Yes | Must be a valid, unexpired quote from Step 3. |
| `bookingId` | string | Yes | Your internal reference. Must be unique per channel. |
| `bookingStatus` | string | Yes | Must be `CONFIRMED`. |
| `guest.email` | string | Yes | Guest email address. |
| `guest.phone` | string | Yes | Guest phone number with country code. |
| `guest.firstName` | string | Yes | Guest first name. |
| `guest.lastName` | string | Yes | Guest last name. |
**Response `201 Created`:**
```json theme={null}
{
"bookingId": "your_unique_booking_id"
}
```
Upon successful creation, the system automatically:
* Blocks inventory for the booked dates
* Assigns an available property unit
* Dispatches confirmation to the guest via email and WhatsApp
Duplicate `bookingId` values within the same channel are rejected with a `500` error. Use your internal order ID to guarantee uniqueness.
***
## Going Live Checklist
Complete each item before switching from Sandbox to Production.
Receive your Production `Api-Key` and `Channel-Id` from the Elivaas integrations team.
Call `GET /v1/cities` and cache the response. Use `slug` values for location filtering.
Integrate `GET /v1/properties/rates` with city slugs, date, and occupancy filters. Verify pagination works correctly.
Add `ratePlanCode` to the search request. Confirm an `id` is returned and stored.
Submit `POST /v2/bookings` with the stored `quoteId`. Verify a `201` response with the `bookingId`.
Implement error handling for `400`, `401`, and `500` responses. Display actionable messages to the user.
Replace the base URL with `https://api.elivaas.com/api` and use Production credentials.
***
## Additional APIs
The following endpoints are not required for the core booking flow but provide capabilities for richer integrations.
Retrieve active promotions and coupon codes to display on property pages.
Query raw availability by date — useful for building calendar views.
Access detailed rate plan definitions including extra guest surcharges.
Bulk-fetch daily rates across multiple properties for rate synchronization.
***
## Error Handling
All endpoints return a consistent error envelope.
```json theme={null}
{
"status": 400,
"message": "Booking ID already exists for this channel",
"errorCode": "BOOKING_ID_DUPLICATE",
"timestamp": "2025-08-01T10:30:00",
"details": "A booking with ID 'order_123' already exists for channel 'chnl_abc'"
}
```
| HTTP Status | Meaning | Recommended Action |
| ------------- | --------------------- | ------------------------------------------------------------------------------------------------------------ |
| `200` / `201` | Success | Process the response body. |
| `400` | Bad Request | Inspect the `message` and `details` fields. Fix the request parameters or body. |
| `401` | Unauthorized | Verify that `Api-Key` and `Channel-Id` are present and valid. |
| `404` | Not Found | The referenced resource does not exist. Confirm the ID is correct. |
| `500` | Internal Server Error | Retry with exponential backoff. If the error persists, contact support with the `timestamp` and `errorCode`. |
***
## Support
For onboarding, technical issues, or credential requests — reach us at [api@elivaas.com](mailto:api@elivaas.com).