Circles

A circle is a group of users who travel together — a family trip, a friends' getaway, or a corporate offsite. Members are invited into the circle, assigned to hotel rooms, and can pool and redeem group perks against shared bookings.

Every endpoint in this section is authenticated as an end user with a Bearer JWT and the white-label app headers:

• Authorization: Bearer <JWT> — issued by your OAuth2 flow
• X-App-Id: <uuid> (or X-App-Slug: <slug>) — identifies your white-label app
• X-Environment: Sandbox | Production — routes to the right environment

Lifecycle

A circle moves through a predictable sequence. Each stage maps to one of the pages in this section.

1. Create — the organizer creates a circle with a name, description, and optional purpose (stays, dining, experiences). See Manage Circles.
2. Invite — members are pulled in by username, by shareable link, or by an invitation code they redeem. Invitees accept or decline, and members can later leave or be removed. See Invites & Membership.
3. Add hotels & rooms — the circle attaches one or more hotels and the rooms it will occupy. See Hotels, Rooms & Allocations.
4. Allocate — members are assigned to specific rooms as occupants, with optional payment-split metadata (who pays, split ratio). See Hotels, Rooms & Allocations.
5. Book & redeem — the circle initiates a group booking and redeems pooled perks against it. See Group Bookings & Perks.

Concepts

• Member vs. occupant — a member belongs to the circle; an occupant is a member allocated to a specific room. A member can belong to the circle without yet occupying a room.
• circle_member_id — the identifier for a member's link to a circle. Occupant operations reference this, not the raw user ID.
• Payment split — room allocations carry optional split metadata (is_payee, split_ratio) and rooms carry payee and has_paid, so the group can track who is footing the bill for each room.

Pages

• Manage Circles — list, create, fetch, and delete circles.
• Invites & Membership — invite by username or link, join, accept, decline, leave, remove.
• Hotels, Rooms & Allocations — attach hotels and rooms, assign members, manage room allocations and occupants.
• Group Bookings & Perks — initiate a group booking and redeem circle perks.

List Circles

GET /v1/circle

Returns all active circles the authenticated user belongs to. No request body.

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