Skip to main content

​
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.
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.

​
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:
​
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa
​
Authorization
string
required
Bearer token for authenticationFormat: Bearer {API_KEY} or Bearer {JWT_TOKEN}

​
Available Endpoints

List Hotel Stays

Retrieve all hotel stays with filtering and pagination

Get Hotel Stay

Retrieve a specific hotel stay by ID

Get Totals

Get aggregated stay count, room-nights, and total CO2e

Impact Calculation

Step-by-step CO2e breakdown for a specific stay

Delete Hotel Stay

Remove a hotel stay record

Bulk Delete

Remove multiple hotel stay records at once

​
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

{
  "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

{
  "items": [
    { "hotel stay object" }
  ],
  "total": 42,
  "page": 1,
  "size": 50,
  "filter_hash": "abc123..."
}

​
Error Handling

​
Common HTTP Status Codes

StatusMeaningSolution
200Success—
204No Content (delete successful)—
400Bad RequestCheck request parameters
401UnauthorizedVerify API key or JWT token
404Not FoundCheck resource ID or organization
422Validation ErrorReview error details in response
500Server ErrorContact support if it persists

​
Error Response Format

{
  "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

Business Travels API

Manage business travel trips (Scope 3 Category 6)

Employees API

Manage employee commuting emissions (Scope 3 Category 7)