---
uuid: 547f981c-8a6c-4773-90f0-b72fe2af1762
date_created: 2025-07-23T07:45:31.915Z
date_updated: 2026-04-03T16:26:41.218Z
seo_url: retrieve-more-accommodations
category: Option creation
tags: 
  - Booking
  - Accommodations
  - Rooms
routes: 
  - POST /v3/proposals/search
  - PUT /v3/proposals/{proposal_id}/attendees
  - GET /v0/products/{product_id}/accommodation_categories
  - POST /v1/accommodations_arrangement/search
  - PUT /v1/proposals/{proposal_id}/accommodations_arrangement
  - GET /v1/proposals/{proposal_id}/accommodations_arrangement
---

# Retrieve More Accommodations

This scenario explains how to extend a proposal with additional accommodation arrangements after the initial search and attendee qualification steps.

## Flow

```mermaid
flowchart LR
    step0["Search for a proposal"]
    step1["Qualify proposal attendees"]
    step2["List the product accommodation categories"]
    step3["Search for additional accommodation arrangements"]
    step4["Add an accommodation arrangement"]
    step5["Review the updated accommodation arrangement"]
    step0 --> step1
    step1 --> step2
    step2 --> step3
    step3 --> step4
    step4 --> step5
    classDef optional fill:transparent,stroke:#ffffff,color:#ffffff,stroke-width:1px,stroke-dasharray: 6\,4
    class step2 optional
```

## Overview

The route sequence combines proposal creation, attendee qualification, accommodation category discovery, arrangement search, arrangement update, and final read-back of the updated repartition.

## Prerequisites

* A proposal must already exist or be created at the start of the sequence.
* `proposal_id` is required on accommodation arrangement routes.
* `product_id` may be needed to resolve accommodation categories.
* `accept-language` and `x-api-key` are required on the documented calls.

## 1 - Search for a proposal

Use `POST /v3/proposals/search` to search for a proposal.

#### Prerequisites

Prepare the parameters required by the call. Keep `x-api-key` and, when the route is customer-scoped, a valid bearer token. Validate the request body before the call to avoid a validation error.

#### Calling CURL

```bash
curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "accept-language: en-US" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "product-1", "start_date": "2026-07-05", "end_date": "2026-07-12", "attendees": [{"birthdate": "1990-03-12"}]}' \
  "https://api.clubmed.com/v3/proposals/search"
```

#### Example answer

```json
[
  {
    "id": "proposal-1",
    "product_id": "product-1",
    "price": {
      "amount": 2890,
      "currency": "EUR"
    },
    "remaining_stock": 4
  }
]
```

> **info:** Keep the returned `proposal_id` to request additional accommodations on the same proposal.

***

**Response codes**

* `200 OK`: the operation succeeds and the resource is returned.
* `400 Bad Request`: the body or parameters are invalid.
* `404 Not Found`: the target resource cannot be found.

**Related route**: [POST https://api.clubmed.com//v3/proposals/search](https://api.clubmed.com/doc?search=POST%20%2Fv3%2Fproposals%2Fsearch)

## 2 - Qualify proposal attendees

Use `PUT /v3/proposals/{proposal_id}/attendees` to qualify proposal attendees.

#### Prerequisites

Prepare `proposal_id`. Keep `x-api-key` and, when the route is customer-scoped, a valid bearer token. Validate the request body before the call to avoid a validation error.

#### Calling CURL

```bash
curl -X PUT \
  -H "x-api-key: YOUR_API_KEY" \
  -H "accept-language: en-US" \
  -H "Content-Type: application/json" \
  -d '{"attendees": [{"id": "attendee-1", "first_name": "Jane", "last_name": "Doe", "birthdate": "1990-03-12"}]}' \
  "https://api.clubmed.com/v3/proposals/{proposal_id}/attendees"
```

#### Example answer

```http
HTTP/1.1 204 No Content
```

> **info:** Success may be returned without a response body. Read the resource again afterwards if you need to display the final state.

***

**Response codes**

* `204 No Content`: the operation is applied successfully.
* `400 Bad Request`: the body or parameters are invalid.
* `404 Not Found`: the target resource cannot be found.

**Related route**: [PUT https://api.clubmed.com//v3/proposals/{proposal\_id}/attendees](https://api.clubmed.com/doc?search=PUT%20%2Fv3%2Fproposals%2F%7Bproposal_id%7D%2Fattendees)

## 3 - List the product accommodation categories

Use `GET /v0/products/{product_id}/accommodation_categories` to understand which room categories can later be requested in the proposal.

#### Prerequisites

Prepare `product_id`. Keep `x-api-key` and, when the route is customer-scoped, a valid bearer token.

#### Calling CURL

```bash
curl -X GET \
  -H "x-api-key: YOUR_API_KEY" \
  -H "accept-language: en-US" \
  "https://api.clubmed.com/v0/products/{product_id}/accommodation_categories"
```

#### Example answer

```json
[
  {
    "id": "cat-1",
    "label": "Superior rooms"
  }
]
```

> **info:** Room categories describe the catalog; proposal-level availability still needs to be checked in the next arrangement search.

***

**Response codes**

* `200 OK`: the expected data is returned.
* `400 Bad Request`: the request is invalid or incomplete.
* `404 Not Found`: the requested resource cannot be found.

**Related route**: [GET https://api.clubmed.com//v0/products/{product\_id}/accommodation\_categories](https://api.clubmed.com/doc?search=GET%20%2Fv0%2Fproducts%2F%7Bproduct_id%7D%2Faccommodation_categories)

## 4 - Search for additional accommodation arrangements

Use `POST /v1/accommodations_arrangement/search` to compare the additional room arrangements that are actually available for the current proposal.

#### Prerequisites

Prepare the parameters required by the call. Keep `x-api-key` and, when the route is customer-scoped, a valid bearer token. Validate the request body before the call to avoid a validation error.

#### Calling CURL

```bash
curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "accept-language: en-US" \
  -H "Content-Type: application/json" \
  -d '[{"id": "room-1", "occupancy": 2, "attendees": [{"id": "attendee-1"}, {"id": "attendee-2"}]}]' \
  "https://api.clubmed.com/v1/accommodations_arrangement/search"
```

#### Example answer

```json
[
  {
    "id": "room-1",
    "remaining_stock": 3,
    "differential_prices": {
      "amount": 120,
      "currency": "EUR"
    }
  }
]
```

> **info:** Compare the returned room splits and price deltas before selecting the arrangement to apply.

***

**Response codes**

* `200 OK`: the operation succeeds and the resource is returned.
* `400 Bad Request`: the body or parameters are invalid.
* `404 Not Found`: the target resource cannot be found.

**Related route**: [POST https://api.clubmed.com//v1/accommodations\_arrangement/search](https://api.clubmed.com/doc?search=POST%20%2Fv1%2Faccommodations_arrangement%2Fsearch)

## 5 - Add an accommodation arrangement

Use `PUT /v1/proposals/{proposal_id}/accommodations_arrangement` to add an accommodation arrangement.

#### Prerequisites

Prepare `proposal_id`. Keep `x-api-key` and, when the route is customer-scoped, a valid bearer token. Validate the request body before the call to avoid a validation error.

#### Calling CURL

```bash
curl -X PUT \
  -H "x-api-key: YOUR_API_KEY" \
  -H "accept-language: en-US" \
  -H "Content-Type: application/json" \
  -d '[{"id": "room-1", "occupancy": 2, "attendees": [{"id": "attendee-1"}, {"id": "attendee-2"}]}]' \
  "https://api.clubmed.com/v1/proposals/{proposal_id}/accommodations_arrangement"
```

#### Example answer

```http
HTTP/1.1 204 No Content
```

> **info:** Success may be returned without a response body. Read the resource again afterwards if you need to display the final state.

***

**Response codes**

* `204 No Content`: the operation is applied successfully.
* `400 Bad Request`: the body or parameters are invalid.
* `404 Not Found`: the target resource cannot be found.

**Related route**: [PUT https://api.clubmed.com//v1/proposals/{proposal\_id}/accommodations\_arrangement](https://api.clubmed.com/doc?search=PUT%20%2Fv1%2Fproposals%2F%7Bproposal_id%7D%2Faccommodations_arrangement)

## 6 - Review the updated accommodation arrangement

Use `GET /v1/proposals/{proposal_id}/accommodations_arrangement` to read back the arrangement currently applied on the proposal after the accommodation change.

#### Prerequisites

Prepare `proposal_id`. Keep `x-api-key` and, when the route is customer-scoped, a valid bearer token.

#### Calling CURL

```bash
curl -X GET \
  -H "x-api-key: YOUR_API_KEY" \
  -H "accept-language: en-US" \
  "https://api.clubmed.com/v1/proposals/{proposal_id}/accommodations_arrangement"
```

#### Example answer

```json
[
  {
    "id": "room-1",
    "label": "Superior Room",
    "attendees": [
      {
        "id": "attendee-1"
      }
    ]
  }
]
```

> **info:** Check households, room assignment, and price consequences before exposing the updated proposal to the user.

***

**Response codes**

* `200 OK`: the expected data is returned.
* `400 Bad Request`: the request is invalid or incomplete.
* `404 Not Found`: the requested resource cannot be found.

**Related route**: [GET https://api.clubmed.com//v1/proposals/{proposal\_id}/accommodations\_arrangement](https://api.clubmed.com/doc?search=GET%20%2Fv1%2Fproposals%2F%7Bproposal_id%7D%2Faccommodations_arrangement)