---
canonical_url: "https://docs.composio.dev/toolkits/bluepillow"
markdown_url: "https://docs.composio.dev/toolkits/bluepillow.md"
product: "platform"
version: null
last_updated: null
---

# Blue Pillow Hotels & Stays

Blue Pillow provides AI agents with hotel and stay discovery, live offer comparison, recommendations, validation, and tracked booking handoff.

- **Category:** ai agents
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 8
- **Triggers:** 0
- **Slug:** `BLUEPILLOW`
- **Version:** 00000000_00

## Tools

### Create Booking Handoff

**Slug:** `BLUEPILLOW_CREATE_BOOKING_HANDOFF`

Create only a tracked Blue Pillow handoff link for the user to continue the booking process. This does not reserve a room, confirm a reservation, or collect payment.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ota` | string | No | Preferred OTA from a current offer. Omit it to let Blue Pillow choose the best price. |
| `dates` | object | Yes | Stay dates to embed in the handoff link. |
| `guests` | object | Yes | Room occupancy to embed in the handoff link. |
| `property_id` | string | Yes | Blue Pillow property ID the user chose. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Discover Destinations Near Coordinates

**Slug:** `BLUEPILLOW_DISCOVER_DESTINATIONS_NEAR`

Find cities, neighborhoods, airports, or points of interest near geographic coordinates.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `language` | string ("en" | "it" | "fr" | "de" | "es" | "pt" | "nl" | "ko" | "pl" | "ja") | No | Language for destination names and display labels. |
| `latitude` | number | Yes | Latitude from -90 to 90. |
| `longitude` | number | Yes | Longitude from -180 to 180. |
| `radius_km` | number | No | Positive search radius in kilometers. |
| `destination_type` | string ("city" | "neighborhood" | "airport" | "poi") | No | Restrict candidates to one destination type. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Property

**Slug:** `BLUEPILLOW_GET_PROPERTY`

Get canonical details and optional review enrichments for one property; use search or hotel recommendation for live availability.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `include` | array | No | Review enrichments to include. reviews_extended supersedes reviews_sample; the list is sent as one comma-separated query value. |
| `currency` | string | No | ISO 4217 pricing currency; defaults from user_country and then to USD. |
| `language` | string | No | Two-letter lowercase language code. |
| `property_id` | string | Yes | Blue Pillow property ID returned by search or recommendation, normally prefixed prop_. |
| `user_country` | string | No | ISO 3166 alpha-2 country for booking-link locale and default pricing currency. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Recommend Offer for Property

**Slug:** `BLUEPILLOW_RECOMMEND_OFFER_FOR_PROPERTY`

Compare live OTA offers and recommend the best offer for a property the user has already selected. This endpoint has no locale or currency input, so Blue Pillow applies provider defaults; use the currency returned in the response.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `dates` | object | Yes | Stay dates; check_out must be after check_in. |
| `guests` | object | Yes | Room occupancy for the stay. |
| `property_id` | string | Yes | Selected Blue Pillow property ID returned by search or recommendation. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Recommend Stay

**Slug:** `BLUEPILLOW_RECOMMEND_STAY`

Rank a location to one recommended stay plus alternatives. A recommendation may have no live price and unknown availability, so validate an offer before booking handoff.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `dates` | object | Yes | Stay dates; check_out must be after check_in. |
| `guests` | object | Yes | Room occupancy for the stay. |
| `context` | object | No | Optional locale and agent context. When supplied, end_user_country and currency are both required. |
| `location` | object | Yes | Recommendation location. Destination IDs can come from Resolve Destination. |
| `constraints` | object | No | Optional price, rating, property, amenity, cancellation, and OTA constraints. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Resolve Destination

**Slug:** `BLUEPILLOW_RESOLVE_DESTINATION`

Resolve a place name into destination IDs for stay search, including ambiguity and confidence information.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Place name to resolve, such as a city, neighborhood, airport, or point of interest. |
| `country` | string | No | Optional country bias used to disambiguate the place name. |
| `language` | string ("en" | "it" | "fr" | "de" | "es" | "pt" | "nl" | "ko" | "pl" | "ja") | No | Language for destination names and display labels. |
| `destination_type` | string ("city" | "neighborhood" | "airport" | "poi") | No | Restrict candidates to a city, neighborhood, airport, or point of interest. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Search Stays

**Slug:** `BLUEPILLOW_SEARCH_STAYS`

Search one page of ranked live stay inventory with availability, prices, OTA offers, and an opaque cursor for more results.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sort` | string ("score_desc" | "price_asc" | "rating_desc" | "conversion_desc") | No | Ranking order for results. |
| `dates` | object | No | Stay dates, required for an initial search and omitted for a cursor-only continuation; check_out must be after check_in. |
| `limit` | integer | No | Maximum results in this page, from 1 to 100. |
| `guests` | object | No | Room occupancy, required for an initial search and omitted for a cursor-only continuation. |
| `filters` | object | No | Optional result filters. |
| `currency` | string | No | Uppercase ISO 4217 currency for returned prices. |
| `language` | string | No | Two-letter lowercase response language code. |
| `location` | object | No | Search location, required for an initial search and omitted for a cursor-only continuation. Prefer a destination_id returned by Resolve Destination. |
| `next_cursor` | string | No | Opaque cursor returned by a previous call. It restores the original search criteria, so continuation may provide this field alone. |
| `user_country` | string | No | Uppercase ISO 3166 alpha-2 country for locale and default currency. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Validate Offer

**Slug:** `BLUEPILLOW_VALIDATE_OFFER`

Re-price a previously seen EUR offer and report whether it remains valid within the provider's two-percent tolerance.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `dates` | object | Yes | Exact stay dates associated with the observed offer. |
| `guests` | object | Yes | Exact room occupancy associated with the observed offer. |
| `property_id` | string | Yes | Blue Pillow property ID for the observed offer. |
| `offer_to_compare` | object | Yes | Previously observed offer expressed in EUR. A numeric amount from another currency must be converted to EUR before comparison. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |