Hotels, Rooms & Allocations

Once a circle has members, attach the hotels it will stay at, add the rooms, and place members into those rooms. Two layers of assignment exist:

• Quick assignment — allocation endpoints place a single user into a room in one call.
• Detailed allocations — room-allocations endpoints model a room's full occupancy: create an allocation for a room, then add or remove occupants and track payment-split metadata.

All endpoints authenticate as the end user with a Bearer JWT plus the X-App-Id and X-Environment headers. {circle_id}, {hotel_id}, {room_id}, {allocation_id}, and {member_id} in the paths are UUIDs.

Payment-split metadata

Room and allocation responses carry payment-split fields so a group can track who pays for each room:

• On a room (RoomPayload): payee — the member responsible for paying — and has_paid (boolean).
• On an allocated occupant (RoomAllocationUserMetadata): is_payee (boolean) marking the paying occupant, and split_ratio (number, optional) for their share of the cost.

These appear in responses; you do not send them when creating allocations.

Add a Hotel

POST /v1/circle/{circle_id}/hotels

Attaches a hotel to the circle.

curl -X POST 'https://cloud.vanitypass.com/v1/circle/{circle_id}/hotels' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: Sandbox' \
  -d '{"id":"hotel_12345","provider":"etg"}'

Remove a Hotel

DELETE /v1/circle/{circle_id}/hotels/{hotel_id}

Removes a hotel from the circle. No request body.

curl -X DELETE 'https://cloud.vanitypass.com/v1/circle/{circle_id}/hotels/{hotel_id}' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: Sandbox' \

Add Rooms to a Hotel

POST /v1/circle/{circle_id}/hotels/{hotel_id}/rooms

Adds one or more rooms to a hotel in the circle. The body is a rooms array; each entry describes a room. All room fields are optional — populate the ones your catalogue provides.

curl -X POST 'https://cloud.vanitypass.com/v1/circle/{circle_id}/hotels/{hotel_id}/rooms' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: Sandbox' \
  -d '{"rooms":[{"id":"room_001","category_name":"Deluxe King","occupants":2,"currency":"AED"}]}'

Remove a Room

DELETE /v1/circle/{circle_id}/hotels/{hotel_id}/rooms/{room_id}

Removes a room from a hotel in the circle. No request body.

curl -X DELETE 'https://cloud.vanitypass.com/v1/circle/{circle_id}/hotels/{hotel_id}/rooms/{room_id}' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: Sandbox' \

Assign a Member to a Room

POST /v1/circle/{circle_id}/allocation

Quick assignment — places a single user into a specific room.

curl -X POST 'https://cloud.vanitypass.com/v1/circle/{circle_id}/allocation' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: Sandbox' \
  -d '{"hotel_id":"hotel_12345","room_id":"room_001","target_user_id":"user_789"}'

Remove a Room Assignment

PUT /v1/circle/{circle_id}/allocation/remove

Removes a quick room assignment. Uses the same body shape as the assign call to identify the room and user.

curl -X PUT 'https://cloud.vanitypass.com/v1/circle/{circle_id}/allocation/remove' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: Sandbox' \
  -d '{"hotel_id":"hotel_12345","room_id":"room_001","target_user_id":"user_789"}'

List Room Allocations

GET /v1/circle/{circle_id}/room-allocations

Lists all detailed room allocations for the circle, including occupants and payment-split metadata. No request body.

curl -X GET 'https://cloud.vanitypass.com/v1/circle/{circle_id}/room-allocations' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: Sandbox' \

Create a Room Allocation

POST /v1/circle/{circle_id}/room-allocations

Creates a detailed allocation for a specific circle hotel room. Occupants are added separately.

curl -X POST 'https://cloud.vanitypass.com/v1/circle/{circle_id}/room-allocations' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: Sandbox' \
  -d '{"hotel_room_id":"hotel_room_abc"}'

Get a Room Allocation

GET /v1/circle/{circle_id}/room-allocations/{allocation_id}

Returns a single allocation with its occupants and payment-split metadata. Returns 404 if not found. No request body.

curl -X GET 'https://cloud.vanitypass.com/v1/circle/{circle_id}/room-allocations/{allocation_id}' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: Sandbox' \

Delete a Room Allocation

DELETE /v1/circle/{circle_id}/room-allocations/{allocation_id}

Deletes an allocation. No request body.

curl -X DELETE 'https://cloud.vanitypass.com/v1/circle/{circle_id}/room-allocations/{allocation_id}' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: Sandbox' \

Add an Occupant

POST /v1/circle/{circle_id}/room-allocations/{allocation_id}/occupants

Adds a circle member as an occupant of the allocation.

curl -X POST 'https://cloud.vanitypass.com/v1/circle/{circle_id}/room-allocations/{allocation_id}/occupants' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: Sandbox' \
  -d '{"circle_member_id":"{member_id}"}'

Remove an Occupant

DELETE /v1/circle/{circle_id}/room-allocations/{allocation_id}/occupants/{member_id}

Removes an occupant from the allocation. No request body.

curl -X DELETE 'https://cloud.vanitypass.com/v1/circle/{circle_id}/room-allocations/{allocation_id}/occupants/{member_id}' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: Sandbox' \