Create Hotel Stay
const options = {
method: 'POST',
headers: {
'x-api-key': '<x-api-key>',
'x-organization-id': '<x-organization-id>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
check_in_date: '<string>',
check_out_date: '<string>',
country: '<string>',
name: '<string>',
hotel_name: '<string>',
address: '<string>',
rooms: 123,
custom_ef_record_id: '<string>',
attachment_file_id: '<string>'
})
};
fetch('https://api.dcycle.io/v1/hotel-stays', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.dcycle.io/v1/hotel-stays"
payload = {
"check_in_date": "<string>",
"check_out_date": "<string>",
"country": "<string>",
"name": "<string>",
"hotel_name": "<string>",
"address": "<string>",
"rooms": 123,
"custom_ef_record_id": "<string>",
"attachment_file_id": "<string>"
}
headers = {
"x-api-key": "<x-api-key>",
"x-organization-id": "<x-organization-id>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)curl --request POST \
--url https://api.dcycle.io/v1/hotel-stays \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--header 'x-organization-id: <x-organization-id>' \
--data '
{
"check_in_date": "<string>",
"check_out_date": "<string>",
"country": "<string>",
"name": "<string>",
"hotel_name": "<string>",
"address": "<string>",
"rooms": 123,
"custom_ef_record_id": "<string>",
"attachment_file_id": "<string>"
}
'{
"id": "<string>",
"organization_id": "<string>",
"name": {},
"check_in_date": "<string>",
"check_out_date": "<string>",
"country": "<string>",
"address": {},
"hotel_name": {},
"rooms": 123,
"status": "<string>",
"source": "<string>",
"file_id": {},
"file_name": {},
"attachment": {
"file_id": "<string>",
"file_name": "<string>",
"file_url": "<string>"
},
"co2e": {},
"uploaded_by": {},
"location_geocode": {},
"created_at": {},
"updated_at": {}
}Create Hotel Stay
Create a hotel stay record and trigger asynchronous CO2e calculation
POST
/
v1
/
hotel-stays
Create Hotel Stay
const options = {
method: 'POST',
headers: {
'x-api-key': '<x-api-key>',
'x-organization-id': '<x-organization-id>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
check_in_date: '<string>',
check_out_date: '<string>',
country: '<string>',
name: '<string>',
hotel_name: '<string>',
address: '<string>',
rooms: 123,
custom_ef_record_id: '<string>',
attachment_file_id: '<string>'
})
};
fetch('https://api.dcycle.io/v1/hotel-stays', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.dcycle.io/v1/hotel-stays"
payload = {
"check_in_date": "<string>",
"check_out_date": "<string>",
"country": "<string>",
"name": "<string>",
"hotel_name": "<string>",
"address": "<string>",
"rooms": 123,
"custom_ef_record_id": "<string>",
"attachment_file_id": "<string>"
}
headers = {
"x-api-key": "<x-api-key>",
"x-organization-id": "<x-organization-id>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)curl --request POST \
--url https://api.dcycle.io/v1/hotel-stays \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--header 'x-organization-id: <x-organization-id>' \
--data '
{
"check_in_date": "<string>",
"check_out_date": "<string>",
"country": "<string>",
"name": "<string>",
"hotel_name": "<string>",
"address": "<string>",
"rooms": 123,
"custom_ef_record_id": "<string>",
"attachment_file_id": "<string>"
}
'{
"id": "<string>",
"organization_id": "<string>",
"name": {},
"check_in_date": "<string>",
"check_out_date": "<string>",
"country": "<string>",
"address": {},
"hotel_name": {},
"rooms": 123,
"status": "<string>",
"source": "<string>",
"file_id": {},
"file_name": {},
"attachment": {
"file_id": "<string>",
"file_name": "<string>",
"file_url": "<string>"
},
"co2e": {},
"uploaded_by": {},
"location_geocode": {},
"created_at": {},
"updated_at": {}
}← Hotel Stays API
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).
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).Request
Headers
Body Parameters
ISO-2 country code (e.g.
ES, GB, US). Must be a country with available emission factors — see Available Countries.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).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 benull initially — it is calculated asynchronously.
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.Show properties
Show properties
The file of your files.
Geocoded location data resolved from the address
| Field | Type | Description |
|---|---|---|
country_code | string | ISO-2 country code |
place_id | string | Place identifier |
address_formatted | string | Full formatted address |
latitude | number | Latitude coordinate |
longitude | number | Longitude coordinate |
Example
curl -X POST "https://api.dcycle.io/v1/hotel-stays" \
-H "x-api-key: ${DCYCLE_API_KEY}" \
-H "x-organization-id: ${DCYCLE_ORG_ID}" \
-H "Content-Type: application/json" \
-d '{
"check_in_date": "2025-03-10",
"check_out_date": "2025-03-13",
"country": "ES",
"hotel_name": "Hotel Madrid Centro",
"name": "Spring conference",
"rooms": 1
}'
import requests
import os
headers = {
"x-api-key": os.getenv("DCYCLE_API_KEY"),
"x-organization-id": os.getenv("DCYCLE_ORG_ID"),
"Content-Type": "application/json",
}
response = requests.post(
"https://api.dcycle.io/v1/hotel-stays",
headers=headers,
json={
"check_in_date": "2025-03-10",
"check_out_date": "2025-03-13",
"country": "ES",
"hotel_name": "Hotel Madrid Centro",
"name": "Spring conference",
"rooms": 1,
},
)
stay = response.json()
print(f"Created: {stay['id']} — {stay['check_in_date']} to {stay['check_out_date']}")
const axios = require('axios');
const headers = {
'x-api-key': process.env.DCYCLE_API_KEY,
'x-organization-id': process.env.DCYCLE_ORG_ID,
'Content-Type': 'application/json',
};
axios.post('https://api.dcycle.io/v1/hotel-stays', {
check_in_date: '2025-03-10',
check_out_date: '2025-03-13',
country: 'ES',
hotel_name: 'Hotel Madrid Centro',
name: 'Spring conference',
rooms: 1,
}, { headers })
.then(response => {
console.log(`Created: ${response.data.id}`);
});
Successful Response
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
"name": "Spring conference",
"check_in_date": "2025-03-10",
"check_out_date": "2025-03-13",
"country": "ES",
"address": null,
"hotel_name": "Hotel Madrid Centro",
"rooms": 1,
"status": "active",
"source": "api",
"file_id": null,
"file_name": null,
"attachment": null,
"co2e": null,
"created_at": "2025-03-01T12:00:00Z",
"updated_at": null,
"uploaded_by": null,
"location_geocode": null
}
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{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}
403 Forbidden
Cause: The authenticated user is not a member of the organization{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}
422 Validation Error
Cause: Check-out date is before check-in date{
"detail": [
{
"loc": ["body", "check_out_date"],
"msg": "check_out_date must be on or after check_in_date",
"type": "value_error"
}
]
}
Related Endpoints
Available Countries
Check which countries have emission factors
List Hotel Stays
Browse all hotel stay records
Was this page helpful?