Skip to main content
POST
Create Hotel Stay
← Hotel Stays API
Deprecated. Use POST /v2/hotel-stays: up to 5,000 hotel stays per request, idempotent, with the emissions calculated asynchronously and webhooks. This endpoint keeps working; its responses carry Deprecation and Link: </v2/hotel-stays>; rel="successor-version" headers. Its responses also carry Sunset: Fri, 30 Apr 2027 00:00:00 GMT: the endpoint is retired on April 30, 2027 (see the changelog).
Create a new hotel stay record. CO2e is calculated asynchronously using DEFRA emission factors based on the country and number of room-nights (rooms × nights).

Request

Headers

string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Body Parameters

string
required
Check-in date in ISO format (YYYY-MM-DD)
string
required
Check-out date in ISO format (YYYY-MM-DD). Must be on or after check_in_date.
string
required
ISO-2 country code (e.g. ES, GB, US). Must be a country with available emission factors — see Available Countries.
string
Label for the trip or traveler (max 255 characters)
string
Name of the hotel (max 255 characters)
string
Plain-text address for geocoding (max 500 characters)
integer
default:"1"
Number of booked rooms (1–10 000)
string
A record of one of your custom emission factor databases, configured for hotel_stays and expressed per room-night, to calculate the stay with instead of the default factor of its country. Errors: MULTIDB_CUSTOM_RECORD_NOT_FOUND_OR_DISABLED, MULTIDB_CUSTOM_RECORD_INCOMPATIBLE_CATEGORY, CUSTOM_RECORD_UNIT_MISMATCH (422).
string
UUID of an uploaded file of your files to attach to the stay as its supporting document, e.g. the hotel’s invoice or the booking confirmation. Not the file the stay was read from. A file you cannot attach answers 404 NOT_FOUND naming File.

Response

Returns the created hotel stay with CO2e fields (HTTP 201). CO2e may be null initially — it is calculated asynchronously.
string
Hotel stay UUID
string
UUID of the owning organization
string | null
Trip or traveler label
string
Check-in date (YYYY-MM-DD)
string
Check-out date (YYYY-MM-DD)
string
ISO-2 country code
string | null
Plain-text address
string | null
Hotel name
integer
Number of booked rooms
string
Record status: active, pending, or deleted
string
How the record was created: api, csv, or manual
string | null
UUID of the source file, if created from a file upload
string | null
Name of the source file, if created from a file upload
object | null
The document attached to the stay (attachment_file_id), or null. Not the file the stay was read from (file_id). A file deleted or moved to the trash is no longer attached.
number | null
Calculated CO2e emissions in tCO2e. null until async calculation completes.
string | null
UUID of the user who created the record
object | null
Geocoded location data resolved from the address
datetime
Creation timestamp
datetime | null
Last update timestamp

Example

Successful Response

co2e is null immediately after creation — it is calculated asynchronously and populated within a few seconds.

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

403 Forbidden

Cause: The authenticated user is not a member of the organization

422 Validation Error

Cause: Check-out date is before check-in date

Available Countries

Check which countries have emission factors

List Hotel Stays

Browse all hotel stay records