> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Hotel Stays API

> Manage hotel stay records and calculate CO2e emissions for Scope 3 Category 6

# Hotel Stays API

The Hotel Stays API allows you to create, retrieve, and delete hotel accommodation records within your organization. Hotel stay emissions are part of **Scope 3 Category 6** according to the GHG Protocol, covering employee accommodation during business travel.

<Note>
  **New API**: This endpoint is part of the new API architecture with improved design and maintainability. Hotel stays are stored separately from business travel trips and have their own dedicated endpoints at `/v1/hotel-stays`.
</Note>

## Key Features

* **Accommodation Records Management**: Create and manage hotel stay records
* **Room-Night Emissions**: Automatic CO2e calculation using DEFRA room-night emission factors per country
* **Bulk CSV Upload**: Upload multiple hotel stays at once via a pre-signed S3 URL
* **Pagination Support**: Efficiently retrieve large lists of hotel stays with filtering

## Authentication

All endpoints require authentication using either:

* **API Key**: Include in `Authorization` header as `Bearer {API_KEY}`
* **JWT Token**: Include in `Authorization` header as `Bearer {JWT_TOKEN}`

## Headers

All requests must include:

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication

  **Format:** `Bearer {API_KEY}` or `Bearer {JWT_TOKEN}`
</ParamField>

## Available Endpoints

<CardGroup cols={2}>
  <Card title="List Hotel Stays" icon="list" href="/api-reference/hotel-stays/list">
    Retrieve all hotel stays with filtering and pagination
  </Card>

  <Card title="Get Hotel Stay" icon="magnifying-glass" href="/api-reference/hotel-stays/get">
    Retrieve a specific hotel stay by ID
  </Card>

  <Card title="Get Totals" icon="chart-bar" href="/api-reference/hotel-stays/totals">
    Get aggregated stay count, room-nights, and total CO2e
  </Card>

  <Card title="Impact Calculation" icon="calculator" href="/api-reference/hotel-stays/impact-calculation">
    Step-by-step CO2e breakdown for a specific stay
  </Card>

  <Card title="Delete Hotel Stay" icon="trash" href="/api-reference/hotel-stays/delete">
    Remove a hotel stay record
  </Card>

  <Card title="Bulk Delete" icon="trash-can" href="/api-reference/hotel-stays/bulk-delete">
    Remove multiple hotel stay records at once
  </Card>
</CardGroup>

## Hotel Stay Attributes

### Core Information

* **name** (`string`, optional): Free-text description of the stay
* **check\_in\_date** (`date`, required): Date the guest checked in
* **check\_out\_date** (`date`, required): Date the guest checked out
* **country** (`string`, required): ISO-3166 alpha-2 country code (e.g. `ES`, `GB`, `US`)
* **city** (`string`, optional): City where the hotel is located
* **hotel\_name** (`string`, optional): Name of the hotel
* **rooms** (`integer`, required): Number of rooms booked (1–10000)

### Status

* **status** (`string`, read-only): `active`, `pending`, or `error`
* **source** (`string`, read-only): How the record was created (`manual`, `bulk_upload`, etc.)
* **co2e** (`number`, read-only): Calculated CO2 equivalent emissions in kg — sourced from `total_impacts`, not stored on the record

## Emission Methodology

CO2e is calculated as:

```
CO2e (kg) = rooms × nights × EF (kg CO2e / room-night)
```

Where:

* **nights** = `check_out_date − check_in_date` in days
* **EF** = DEFRA hotel room-night emission factor for the stay's country

One `total_impacts` row is created per night, enabling accurate pro-rating when the stay spans a reporting period boundary.

## Response Format

### Hotel Stay Object

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
  "name": "Team offsite — Madrid",
  "check_in_date": "2024-11-04",
  "check_out_date": "2024-11-07",
  "country": "ES",
  "city": "Madrid",
  "hotel_name": "Hotel Gran Vía",
  "rooms": 3,
  "status": "active",
  "source": "manual",
  "co2e": 18.54,
  "file_id": null,
  "file_name": null,
  "created_at": "2024-11-01T09:00:00Z",
  "updated_at": "2024-11-01T09:00:00Z",
  "uploaded_by": {
    "id": "b9f1e2d3-...",
    "first_name": "Ana",
    "last_name": "García"
  }
}
```

### Pagination Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    { "hotel stay object" }
  ],
  "total": 42,
  "page": 1,
  "size": 50,
  "filter_hash": "abc123..."
}
```

## Error Handling

### Common HTTP Status Codes

| Status | Meaning                        | Solution                          |
| ------ | ------------------------------ | --------------------------------- |
| 200    | Success                        | —                                 |
| 204    | No Content (delete successful) | —                                 |
| 400    | Bad Request                    | Check request parameters          |
| 401    | Unauthorized                   | Verify API key or JWT token       |
| 404    | Not Found                      | Check resource ID or organization |
| 422    | Validation Error               | Review error details in response  |
| 500    | Server Error                   | Contact support if it persists    |

### Error Response Format

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Error description",
  "code": "ERROR_CODE"
}
```

## GHG Protocol Context

Hotel stay emissions fall under **Scope 3, Category 6** of the GHG Protocol alongside business travel trips:

* **Scope 3**: Indirect emissions from value chain activities
* **Category 6**: Business Travel — emissions from employee travel and accommodation for work purposes

## Related Documentation

<CardGroup cols={2}>
  <Card title="Business Travels API" icon="plane" href="/api-reference/business-travels/overview">
    Manage business travel trips (Scope 3 Category 6)
  </Card>

  <Card title="Employees API" icon="users" href="/api-reference/employees/overview">
    Manage employee commuting emissions (Scope 3 Category 7)
  </Card>
</CardGroup>