Properties Details

Retrieve a paginated list of detailed property information for your partner account.

Endpoint

GET /partners/properties/details

Returns a paginated list of all publishable properties associated with your partner account. Each property includes full details such as address, amenities, pricing, media, and policies. The endpoint uses cursor-based pagination — iterate through pages by passing the nextCursor value from each response as the cursor parameter of the next request.

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer token obtained from the authentication endpoint. Format: `Bearer {ACCESS_TOKEN}`
Api-Version	No	API version to use. Defaults to `1`. Currently only `1` is supported.

Query Parameters

Parameter	Type	Required	Default	Description
cursor	string	No	—	Cursor pointing to the last property of the previous page. Omit to retrieve the first page.
pageSize	integer	No	50	Number of properties to return per page. Must be between 1 and 100.

Example Request

curl --location 'https://api.theblueground.com/partners/properties/details?pageSize=50' \
  --header 'Authorization: Bearer {ACCESS_TOKEN}' \
  --header 'Api-Version: 1'

To fetch the next page, pass the nextCursor value from the previous response:

curl --location 'https://api.theblueground.com/partners/properties/details?pageSize=50&cursor={NEXT_CURSOR}' \
  --header 'Authorization: Bearer {ACCESS_TOKEN}' \
  --header 'Api-Version: 1'

Response

Status Codes

Code	Description
200	Success
400	Bad request — see error codes below
401	Unauthorized — invalid or expired access token

Error Codes

When the request fails, the response body includes an error code and message:

Code	HTTP Status	Description
`INVALID_CURSOR`	400	The cursor is not valid
`INVALID_PAGE_SIZE`	400	Page size must be between 1 and 100
`UNSUPPORTED_API_VERSION`	400	The provided `Api-Version` header value is not supported

Response Body

The response is a paginated object containing a list of properties and a cursor for the next page.

PropertyBasicInfoPage

Field	Type	Required	Description
nextCursor	string	No	Cursor to use in the next request to retrieve the following page. `null` when this is the last page.
properties	Object[]	Yes	List of properties for the current page. See PropertyBasicInfo

PropertyBasicInfo

Each entry in the properties array represents a single property with the following fields:

Field	Type	Required	Description
id	string	Yes	Unique property identifier
code	string	Yes	Short human-readable property code (e.g., `NYC-47`)
name	string	Yes	Full property name
type	string	Yes	Property type. See PropertyType
bedrooms	integer	Yes	Number of bedrooms
bathrooms	integer	Yes	Number of bathrooms
wcs	integer	Yes	Number of water closets (toilets without a bathtub or shower)
sizeSqft	number	No	Property size in square feet
sizeSqM	number	No	Property size in square meters
floor	integer	Yes	Floor number where the property is located
maxGuests	integer	No	Maximum number of guests allowed
url	string	Yes	Blueground listing URL for the property
description	string	Yes	Property description text
updatedAt	number	Yes	Unix timestamp (seconds since epoch) of the last update to this property
availability	Object	Yes	Availability and stay restriction information. See PropertyAvailability
address	Object	Yes	Full address details including coordinates. See PropertyAddress
contact	Object	Yes	Agent contact information. See PropertyContact
media	Object	Yes	Photos, 3D tour, and floor plan. See PropertyMedia
amenities	Object[]	Yes	In-unit and building-level amenities directly associated with the unit. See PropertyAmenity
buildingAmenities	Object[]	Yes	Shared amenities available in the building. See PropertyBuildingAmenity
pricing	Object	Yes	Pricing, surcharges, and length-of-stay discounts. See PropertyPricing
policies	Object	Yes	Check-in/out times and guest policy rules. See PropertyPolicies

PropertyType

Describes the physical type of the property.

Possible values: HOUSE, LOFT, MAISONETTE, TOWNHOUSE, PENTHOUSE, APARTMENT, VILLA, DUPLEX, DUPLEX_PENTHOUSE, TRIPLEX, CARRIAGE_HOUSE, ACCESSORY_DWELLING_UNIT, OFFICE, WAREHOUSE

PropertyAvailability

Contains information about when the property is available and for how long guests can stay.

Field	Type	Required	Description
availableFrom	string	Yes	Earliest available check-in date. Format: `yyyy-MM-dd` (e.g., `2026-04-01`)
minimumStay	Object	Yes	Minimum required stay length. See AvailabilityMinMaxStay
maximumStay	Object	No	Maximum allowed stay length. `null` if there is no upper limit. See AvailabilityMinMaxStay
advancedNotice	integer	Yes	Number of days of advance notice required before check-in

AvailabilityMinMaxStay

Field	Type	Required	Description
value	integer	Yes	Duration value
type	string	Yes	Unit of the duration. Either `MONTH` or `NIGHT`

PropertyAddress

Full address with geographic coordinates. county and state are only populated for regions where these administrative levels apply.

Field	Type	Required	Description
streetName	string	Yes	Street name
streetNumber	string	Yes	Street number
postalCode	string	Yes	Postal code
city	string	Yes	City
area	string	Yes	Neighborhood or area within the city
county	string	No	County. Only present in applicable regions
state	string	No	State or province. Only present in applicable regions
country	string	Yes	Country
formattedAddress	string	Yes	Full human-readable address
latitude	decimal	Yes	Geographic latitude
longitude	decimal	Yes	Geographic longitude

PropertyContact

Contact information for the agent responsible for the property.

Field	Type	Required	Description
agentName	string	Yes	Agent's full name
email	string	Yes	Agent's email address
phone	string	Yes	Agent's phone number

PropertyMedia

Media assets associated with the property.

Field	Type	Required	Description
photos	Object[]	Yes	List of property photos. See MediaPhoto
threeDTour	string	No	URL to a 3D virtual tour
floorplan	string	No	URL to the floor plan image or PDF

MediaPhoto

Field	Type	Required	Description
url	string	Yes	Photo URL
caption	string	No	Descriptive caption for the photo

PropertyAmenity

Represents a single amenity directly associated with the unit. The location, details, and type fields provide additional context and are only relevant for specific amenities (e.g., PARKING, WASHING_MACHINE, DRYER).

Field	Type	Required	Description
name	string	Yes	Amenity identifier. See PropertyAmenity values
location	string	No	Where the amenity is located. `IN_UNIT`, `SAME_FLOOR`, or `BUILDING`
details	string	No	Availability of the amenity. `ALWAYS_AVAILABLE` or `UPON_AVAILABILITY`
type	string	No	Sub-type for amenities that have variants (e.g., parking type). See PropertyAmenityType values

PropertyAmenity values: AIR_CONDITIONING, BALCONY, COFFEE_MACHINE, DISHWASHER, DOORMAN, DRYER, ELEVATOR, HAIR_DRYER, IRON, KETTLE, MICROWAVE, OVEN, PARKING, REFRIGERATOR, SPEAKER, STOVE, TOASTER, TV, VACUUM_CLEANER, WASHING_MACHINE, WIFI

PropertyAmenityType values: Applicable to PARKING: GROUND_LEVEL_COVERED, GROUND_LEVEL_UNCOVERED, LIFT, MULTI_LEVEL_COVERED, UNDERGROUND, VALET

PropertyBuildingAmenity

Represents a shared amenity available in the building. Unlike unit amenities, building amenities do not carry additional location or availability metadata.

Field	Type	Required	Description
name	string	Yes	Building amenity identifier. See PropertyBuildingAmenity values

PropertyBuildingAmenity values: ART_GALLERY, BASKETBALL_COURT, BBQ, BIKE_STORAGE, BOCCE_BALL_COURT, BUSINESS_CENTER, CAR_WASH, COFFEE_BAR, CONFERENCE_ROOM, COURTYARD, COVERED_OUTDOOR_PARKING, DOORMAN, ELECTRIC_VEHICLE_CHARGING_STATION, ELEVATOR, ENTERTAINMENT_ROOM, ENTERTAINMENT_SPACE_WITH_KITCHEN, FIRE_PIT, FITNESS_CENTER, GAME_ROOM, GROUND_LEVEL_COVERED, GROUND_LEVEL_UNCOVERED, GYMNASTICS_HALL, INDOOR_BASKETBALL_COURT, INDOOR_SWIMMING_POOL, JACUZZI, LIBRARY, LOUNGE, MEDIA_ROOM, MULTI_LEVEL_COVERED, ON_STREET, OUTDOOR_ENTERTAINMENT_AREA, OUTDOOR_FIREPIT, PADEL_COURT, PET_AREA, PLAY_ROOM, PLAYGROUND, PRIVATE_GARDEN, PRIVATE_SWIMMING_POOL, RESERVABLE_DINNER_ROOM, RESIDENT_CLUB, ROCK_CLIMBING_WALL, ROLLERBLADING_AREA, ROOFTOP, ROOFTOP_BBQ, ROOFTOP_SWIMMING_POOL, RUNNING_TRACK, SAUNA, SCREENING_ROOM, SECURITY_24_7, SHARED_GARDEN, SHARED_SWIMMING_POOL, SHOPPING_MALL_ACCESS, SKATEBOARDING_AREA, SOCCER_FIELD, SPA, SQUASH_COURT, TENNIS_COURT, UNDERGROUND_PARKING, VIRTUAL_GOLF_ROOM, WINE_LOCKERS

PropertyPricing

Pricing information including the advertised price, any applicable surcharges, and length-of-stay discounts.

Field	Type	Required	Description
currency	string	Yes	ISO 4217 currency code (e.g., `USD`, `EUR`)
advertisedPrice	decimal	Yes	Advertised monthly rent price
surcharges	Object[]	Yes	List of additional fees associated with a booking. See PricingSurcharge
discounts	Object[]	Yes	Length-of-stay discount tiers. See PricingDiscount

PricingSurcharge

An additional fee associated with a booking.

Field	Type	Required	Description
type	string	Yes	Surcharge type identifier. Known values: `CLEANING_EXIT`, `HOTEL_TAX`, `CITY_TAX`, `UTILITIES`, `COMMON_FEES`, `OCCUPANCY_FEE`, `OCCUPANCY_STATE_FEE`, `BOOKING`, `CONTRACT_AND_HANDLING`, `SALES_TAX`, `CLIENT_INSURANCE`, `MRA_TAX`, `COUNTY_TAX`, `LOCAL_TAX`, `TOURISM_FEE`, `SERVICE`, `SECURITY_DEPOSIT`. Other values possible.
amount	decimal	Yes	Fee amount in the property's currency
includedInRent	boolean	Yes	Whether this fee is already included in the `advertisedPrice`
mandatory	boolean	Yes	Whether this fee is mandatory for all bookings
timing	string	Yes	`ONE_OFF` for a single charge, or `MONTHLY` for a recurring fee
refundable	boolean	Yes	Whether this fee is refundable upon checkout
displayName	string	Yes	Human-readable name suitable for display in a UI
description	string	No	Additional details about the surcharge

PricingDiscount

A discount tier based on length of stay.

Field	Type	Required	Description
minExclusive	integer	Yes	Minimum stay in nights (exclusive) for this discount tier
maxInclusive	integer	No	Maximum stay in nights (inclusive) for this discount tier. `null` for the open-ended top tier
discountPercentage	decimal	Yes	Discount applied as a percentage of the advertised price

PropertyPolicies

Rules and restrictions that apply to a stay at the property.

Field	Type	Required	Description
checkInTime	string	No	Earliest check-in time (e.g., `15:00`)
checkOutTime	string	No	Latest check-out time (e.g., `11:00`)
petsAllowed	boolean	Yes	Whether pets are permitted
childrenAllowed	boolean	Yes	Whether children are permitted
smokingAllowed	boolean	Yes	Whether smoking is permitted
partyAllowed	boolean	Yes	Whether parties or events are permitted
guestPolicy	string	No	Description of the guest policy
registrationNumber	string	No	Official property registration number. Only present in markets where registration is required

Example Response

{
  "nextCursor": "64f1a2b3c4d5e6f7a8b9c0d1",
  "properties": [
    {
      "id": "64f1a2b3c4d5e6f7a8b9c0d0",
      "code": "ATH-001",
      "name": "Modern Apartment in Kolonaki",
      "type": "APARTMENT",
      "bedrooms": 2,
      "bathrooms": 1,
      "wcs": 1,
      "sizeSqft": 850.0,
      "sizeSqM": 79.0,
      "floor": 3,
      "maxGuests": 4,
      "url": "https://www.theblueground.com/furnished-apartment-kolonaki-athens-ATH-001",
      "description": "A beautifully furnished apartment in the heart of Kolonaki.",
      "updatedAt": 1573821618.252,
      "availability": {
        "availableFrom": "2026-04-01",
        "minimumStay": { "value": 1, "type": "MONTH" },
        "maximumStay": null,
        "advancedNotice": 2
      },
      "address": {
        "streetName": "Patriarchou Ioakeim",
        "streetNumber": "15",
        "postalCode": "10674",
        "city": "Athens",
        "area": "Kolonaki",
        "county": null,
        "state": null,
        "country": "Greece",
        "formattedAddress": "Patriarchou Ioakeim 15, Kolonaki, Athens 10674, Greece",
        "latitude": 37.9768,
        "longitude": 23.7425
      },
      "contact": {
        "agentName": "Maria Papadopoulou",
        "email": "maria@blueground.com",
        "phone": "+30 210 1234567"
      },
      "media": {
        "photos": [
          { "url": "https://cdn.example.com/photo1.jpg", "caption": "Living room" },
          { "url": "https://cdn.example.com/photo2.jpg", "caption": "Bedroom" }
        ],
        "threeDTour": null,
        "floorplan": "https://cdn.example.com/floorplan.pdf"
      },
      "amenities": [
        { "name": "WIFI", "location": "IN_UNIT", "details": "ALWAYS_AVAILABLE", "type": null },
        { "name": "PARKING", "location": "BUILDING", "details": "UPON_AVAILABILITY", "type": "UNDERGROUND" }
      ],
      "buildingAmenities": [{ "name": "ELEVATOR" }, { "name": "FITNESS_CENTER" }],
      "pricing": {
        "currency": "EUR",
        "advertisedPrice": 2400.0,
        "surcharges": [
          {
            "type": "CLEANING_EXIT",
            "amount": 150.0,
            "includedInRent": false,
            "mandatory": true,
            "timing": "ONE_OFF",
            "refundable": false,
            "displayName": "Cleaning Fee",
            "description": "One-time cleaning fee charged at the end of the stay"
          }
        ],
        "discounts": [
          { "minExclusive": 90, "maxInclusive": 180, "discountPercentage": 5.0 },
          { "minExclusive": 180, "maxInclusive": null, "discountPercentage": 10.0 }
        ]
      },
      "policies": {
        "checkInTime": "15:00",
        "checkOutTime": "11:00",
        "petsAllowed": false,
        "childrenAllowed": true,
        "smokingAllowed": false,
        "partyAllowed": false,
        "guestPolicy": "Maximum 4 guests allowed",
        "registrationNumber": "GR-00012345"
      }
    }
  ]
}

Properties Details

On this page