Skip to main content
GET
/
v1
/
hotel-stays
List Hotel Stays
const options = {
  method: 'GET',
  headers: {Authorization: '<authorization>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/hotel-stays', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "items": {
    "id": "<string>",
    "organization_id": "<string>",
    "name": {},
    "check_in_date": "<string>",
    "check_out_date": "<string>",
    "country": "<string>",
    "city": {},
    "hotel_name": {},
    "rooms": 123,
    "status": "<string>",
    "source": {},
    "co2e": {},
    "file_id": {},
    "file_name": {},
    "created_at": {},
    "updated_at": {},
    "uploaded_by": {
      "id": "<string>",
      "first_name": {},
      "last_name": {},
      "profile_img_url": {}
    }
  },
  "total": 123,
  "page": 123,
  "size": 123,
  "filter_hash": "<string>"
}

​
List Hotel Stays

Retrieve a paginated list of hotel stay records for your organization, with support for filtering by status, date range, name, and file.

​
Request

​
Headers

​
Authorization
string
required
Bearer token for authenticationExample: Bearer sk_live_1234567890abcdef
​
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

​
Query Parameters

​
status[]
array[string]
Filter by statusAvailable values: active, pending, errorExample: status[]=active
​
start_date
date
Filter for stays that overlap this start date (inclusive)Format: YYYY-MM-DDExample: 2024-01-01
​
end_date
date
Filter for stays that overlap this end date (inclusive)Format: YYYY-MM-DDExample: 2024-12-31
​
name
string
Filter by name (partial match, case-insensitive)Example: offsite
​
file_id[]
array[uuid]
Filter by source file UUID. Pass 00000000-0000-0000-0000-000000000000 to filter for stays with no associated file.Example: file_id[]=3fa85f64-5717-4562-b3fc-2c963f66afa6
​
created_at_from
datetime
Filter by minimum creation time (inclusive)Format: YYYY-MM-DDTHH:MM:SSZ
​
created_at_to
datetime
Filter by maximum creation time (inclusive)Format: YYYY-MM-DDTHH:MM:SSZ
​
sort
array[string]
Sort order. Prefix with - for descending.Example: sort=-check_in_date
​
page
integer
default:"1"
Page number for pagination
​
size
integer
default:"50"
Items per page (max 100)

​
Response

​
items
array[object]
Array of hotel stay objects
​
total
integer
Total number of records matching the filter
​
page
integer
Current page number
​
size
integer
Items per page
​
filter_hash
string
Hash of the current filter state — use to detect if filters have changed

​
Example

curl -X GET "https://api.dcycle.io/v1/hotel-stays?page=1&size=50&status[]=active&start_date=2024-01-01&end_date=2024-12-31" \
  -H "Authorization: Bearer ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

​
Successful Response

{
  "items": [
    {
      "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-0000-0000-0000-000000000001",
        "first_name": "Ana",
        "last_name": "García",
        "profile_img_url": null
      }
    }
  ],
  "total": 42,
  "page": 1,
  "size": 50,
  "filter_hash": "d4f9a2..."
}

Get Hotel Stay

Get a specific stay by ID

Get Totals

Get aggregated stats across all stays