---
uuid: b185065a-01cb-4619-80fd-969ea4cbc4af
date_created: 2025-10-21T09:43:38.613Z
date_updated: 2026-04-02T23:15:27.308Z
seo_url: add-attendees-to-your-proposal
category: Booking
tags: 
  - Customers
  - Booking
routes: 
  - POST /v1/proposals/search/best
  - PUT /v3/proposals/{proposal_id}/attendees
---

# Add attendees to your proposal

This scenario explains how to create or retrieve a proposal and then attach the expected attendees before later booking or repricing steps.

## Flow

```mermaid
flowchart LR
    step0["Create or retrieve a proposal"]
    step1["Attach attendees to the proposal"]
    step0 --> step1
```

## Overview

This sequence starts by creating or retrieving a proposal with `POST /v1/proposals/search/best`, then updates the traveler list with `PUT /v3/proposals/{proposal_id}/attendees`. It is a common prerequisite before repricing, proposal persistence, or booking creation.

## Prerequisites

* The proposal search criteria used by your integration must be available.
* The `proposal_id` returned by the first step is required for the attendee update.
* The documented calls require `accept-language` and `x-api-key`.

## 1 - Create or retrieve a proposal

Use this route to create or retrieve the best proposal matching the stay criteria sent by your integration. The response returns the proposal identifier to reuse when attaching attendees in the next step.

#### Prerequisites

* `accept-language` and `x-api-key` are required.
* The request body must carry the proposal search criteria expected by your journey.
* Keep the returned `id`: it will be reused as `proposal_id` in the next step.

#### Calling CURL

```bash
curl -X 'POST' \
  'https://api.clubmed.com/v1/proposals/search/best' \
  -H 'accept: application/json' \
  -H 'accept-language: en-US' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json'
```

#### Example answer

```json
{
  "id": "123456",
  "product_id": "MPAC",
  "booking_id": 123456,
  "package_id": "AI",
  "label": "Proposal with one club room",
  "price": {
    "total": 9815.4,
    "currency": "EUR"
  },
  "option_durability": {
    "expiration_date_time": "20160415T10:23:00.234Z",
    "is_reliable": true
  },
  "households": [
    {
      "attendees": [
        {
          "id": "A",
          "birthdate": "20100430",
          "customer_id": "string",
          "customer_type": "NEW_CUSTOMER"
        }
      ]
    }
  ],
  "is_bookable": false
}
```

> **info:** the response can also expose `alternative_price`, `included_services`, and `package_options` when the proposal calculation contains promotions or optional services.

***

**Response codes**

* **OK Response (200):** the proposal was created or retrieved successfully and the payload returns the reusable proposal context.
* **Error (400):** the criteria or payload are invalid, incomplete, or inconsistent with the attendee and accommodation rules documented in Swagger.
* **Error (401):** the request is unauthorized because the authentication data or API key is missing, invalid, or expired.
* **Error (403):** at least one customer carried by the criteria is not allowed to proceed with the booking flow.
* **Error (404):** the requested product is unknown for the provided `product_id`.

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

## 2 - Attach attendees to the proposal

Use this route to update the attendee list attached to an existing proposal. Run it after proposal creation to identify the travelers and persist the customer statuses needed for downstream save or booking steps.

#### Prerequisites

* The `proposal_id` path parameter is required.
* `x-api-key` is required and `accept-language` is documented for the call.
* The request body must carry the list of attendees to attach or update on the proposal.
* `partner_type` and `call_id` can be added when your partner flow requires them.

#### Calling CURL

```bash
curl -X 'PUT' \
  'https://api.clubmed.com/v3/proposals/123456/attendees' \
  -H 'accept: application/json' \
  -H 'accept-language: en-US' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json'
```

#### Example answer

```json
[
  {
    "attendees": [
      {
        "id": "A",
        "customer_id": "123456789",
        "customer_status": "NEW_CUSTOMER",
        "loyalty_status": "GOLD"
      }
    ]
  }
]
```

> **info:** the proposal can become economically invalid between the initial search and the attendee update; in that case the route may return `409`.

***

**Response codes**

* **OK Response (200):** the attendee list was updated successfully for the targeted proposal.
* **Error (400):** the payload is invalid or incomplete, for example when mandatory traveler data is missing, duplicated, or inconsistent.
* **Error (401):** the request is unauthorized because the authentication data or API key is missing, invalid, or expired.
* **Error (403):** at least one added customer is not allowed to proceed with the booking flow.
* **Error (409):** the economic control of the proposal is no longer valid at update time.

**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)