{"openapi":"3.1.0","info":{"title":"Rentiful Open Data API","version":"v1","description":"Rentiful Open Data v1 contract for BTR homes. This is a public contract derived from the current data model, not a complete internal domain dump."},"components":{"schemas":{"Place":{"title":"Place","description":"Rentiful Open Data v1 contract schema for Place. This is a public contract derived from the current data model, not a complete internal domain dump.","type":"object","properties":{"placeId":{"type":"string","description":"Canonical public identifier for this Place. Opaque, human-friendly key.","pattern":"^p_[a-z2-7]{10}$","examples":["p_6Z6NHYUYZJ"]},"operatorId":{"type":"string","description":"The current managing brand for this Place. This may change over time and is not part of the Place's identity.","pattern":"^o_[a-z2-7]{10}$"},"name":{"type":"string","description":"The branded name of this Place (e.g., 'Wembley Park', 'East Village').","minLength":1},"idUrl":{"type":"string","description":"Immutable, ID-based identity URL for this entity. Uses the Place ID token in the path (eg /places/{token}), never the handle, and never includes a country prefix. Stable, immutable, deterministic.","format":"uri"},"dataUrl":{"type":"string","description":"Direct JSON endpoint on the Property Service open data domain. Format: https://{env}.property.rentiful.ai/data/v1/{entityTypePlural}/{entityId}. Same domain family as schemas and OpenAPI.","format":"uri"},"handle":{"type":"string","description":"Optional human-readable handle for this entity. A mutable alias, not part of identity. Identity remains the canonical placeId.","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":2,"maxLength":64},"canonicalUrl":{"type":"string","description":"Canonical Rentiful URL (SEO canonical). Format: https://rentiful.ai/{cc}/places/{handle}. Requires handle and countryCode. Mutable, may change if handle changes. May be omitted if handle or countryCode is not available.","format":"uri"},"url":{"type":"string","description":"Public URL for this Place, if available.","format":"uri"},"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code for this Place (e.g., 'gb', 'ae'). Used for region-scoped marketing URLs. Optional.","pattern":"^[a-z]{2}$","examples":["gb","ae","us"]}},"required":["placeId","operatorId","name"],"additionalProperties":false,"x-generated-at":"2026-04-07T09:04:12.735Z","x-contract":{"entity":"Place","version":"v1"}},"Collection":{"title":"Collection","description":"Rentiful Open Data v1 contract schema for Collection. This is a public contract derived from the current data model, not a complete internal domain dump.","type":"object","properties":{"collectionId":{"type":"string","description":"Canonical public identifier for this Collection. Opaque, human-friendly key.","pattern":"^c_[a-z2-7]{10}$","examples":["c_3MKTYR7II"]},"placeId":{"type":"string","description":"The Place this Collection belongs to. A Collection always belongs to a Place.","pattern":"^p_[a-z2-7]{10}$"},"operatorId":{"type":"string","description":"The current managing brand for this Collection. This may change over time and is not part of the Collection's identity.","pattern":"^o_[a-z2-7]{10}$"},"name":{"type":"string","description":"The name of this Collection (e.g., 'Ferrum', 'Portlands Place', 'Luna').","minLength":1},"idUrl":{"type":"string","description":"Immutable, ID-based identity URL for this entity. Uses the Collection ID token in the path (eg /collections/{token}), never the handle, and never includes a country prefix. Stable, immutable, deterministic.","format":"uri"},"dataUrl":{"type":"string","description":"Direct JSON endpoint on the Property Service open data domain. Format: https://{env}.property.rentiful.ai/data/v1/{entityTypePlural}/{entityId}. Same domain family as schemas and OpenAPI.","format":"uri"},"handle":{"type":"string","description":"Optional human-readable handle for this entity. A mutable alias, not part of identity. Identity remains the canonical collectionId.","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":2,"maxLength":64},"canonicalUrl":{"type":"string","description":"Canonical Rentiful URL (SEO canonical). Format: https://rentiful.ai/{cc}/places/{placeHandle}/collections/{handle}. Requires handle, placeHandle, and countryCode. Mutable, may change if handle changes. May be omitted if handle, placeHandle, or countryCode is not available.","format":"uri"}},"required":["collectionId","placeId","operatorId","name"],"additionalProperties":false,"x-generated-at":"2026-04-07T09:04:12.735Z","x-contract":{"entity":"Collection","version":"v1"}},"Building":{"title":"Building","description":"Rentiful Open Data v1 contract schema for Building. This is a public contract derived from the current data model, not a complete internal domain dump.","type":"object","properties":{"buildingId":{"type":"string","description":"Canonical public identifier for this Building. Opaque, human-friendly key.","pattern":"^b_[a-z2-7]{10}$","examples":["b_7D22PE7FLE"]},"collectionId":{"type":"string","description":"The Collection this Building belongs to, if any. A Building may belong to a Collection.","pattern":"^c_[a-z2-7]{10}$"},"placeId":{"type":"string","description":"The Place this Building belongs to. A Building always belongs to a Place.","pattern":"^p_[a-z2-7]{10}$"},"operatorId":{"type":"string","description":"The current managing brand for this Building. This may change over time and is not part of the Building's identity.","pattern":"^o_[a-z2-7]{10}$"},"name":{"type":"string","description":"The name of this Building (e.g., 'Sky Point', 'Landsby East').","minLength":1},"idUrl":{"type":"string","description":"Immutable, ID-based identity URL for this entity. Uses the Building ID token in the path (eg /buildings/{token}), never the handle, and never includes a country prefix. Stable, immutable, deterministic.","format":"uri"},"dataUrl":{"type":"string","description":"Direct JSON endpoint on the Property Service open data domain. Format: https://{env}.property.rentiful.ai/data/v1/{entityTypePlural}/{entityId}. Same domain family as schemas and OpenAPI.","format":"uri"},"handle":{"type":"string","description":"Optional human-readable handle for this entity. A mutable alias, not part of identity. Identity remains the canonical buildingId.","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":2,"maxLength":64},"canonicalUrl":{"type":"string","description":"Canonical Rentiful URL (SEO canonical). Format: https://rentiful.ai/{cc}/places/{placeHandle}/buildings/{handle}. Requires handle, placeHandle, and countryCode. Mutable, may change if handle changes. May be omitted if handle, placeHandle, or countryCode is not available.","format":"uri"},"url":{"type":"string","description":"Public URL for this Building, if available.","format":"uri"},"streetAddress":{"type":"string","description":"Street address for this Building."},"city":{"type":"string","description":"City where this Building is located."},"postcode":{"type":"string","description":"Postal code for this Building."},"lat":{"type":"number","description":"Latitude coordinate for this Building.","minimum":-90,"maximum":90},"lng":{"type":"number","description":"Longitude coordinate for this Building.","minimum":-180,"maximum":180}},"required":["buildingId","placeId","operatorId","name"],"additionalProperties":false,"x-generated-at":"2026-04-07T09:04:12.735Z","x-contract":{"entity":"Building","version":"v1"}},"Unit":{"title":"Unit","description":"Rentiful Open Data v1 contract schema for Unit. This is a public contract derived from the current data model, not a complete internal domain dump. Unit represents the publicly presented rentable home. In co-living or student housing this may be an individual bedroom within a shared flat, rather than a self-contained apartment.","type":"object","properties":{"unitId":{"type":"string","description":"Canonical public identifier for this Unit. Opaque, human-friendly key.","pattern":"^u_[a-z2-7]{10}$","examples":["u_JWKZ7JYTLO"]},"buildingId":{"type":"string","description":"The Building this Unit belongs to (authoritative parent). A Unit always belongs to a Building.","pattern":"^b_[a-z2-7]{10}$"},"collectionId":{"type":"string","description":"The Collection this Unit belongs to, if any (derived/read-only). Derived from the Unit's Building.","pattern":"^c_[a-z2-7]{10}$"},"placeId":{"type":"string","description":"The Place this Unit belongs to (derived/read-only, required). Derived from the Unit's Building.","pattern":"^p_[a-z2-7]{10}$"},"operatorId":{"type":"string","description":"The current managing brand for this Unit. This may change over time and is not part of the Unit's identity.","pattern":"^o_[a-z2-7]{10}$"},"name":{"type":"string","description":"The name or identifier of this Unit (e.g., 'Apartment 101', 'Flat 12A')."},"bedrooms":{"type":"integer","description":"Number of bedrooms in this Unit.","minimum":0},"bathrooms":{"type":"integer","description":"Number of bathrooms in this Unit.","minimum":0},"sqm":{"type":"number","description":"Size of this Unit in square meters.","minimum":0},"floor":{"type":"integer","description":"Floor number for this Unit (integer)."},"structureType":{"type":"string","description":"The physical dwelling form of this Unit (standardized).","enum":["apartment","house","townhouse","bungalow","room","ensuite_room","shared_room","annexe","other"]},"layoutType":{"type":"string","description":"Standardized layout classification for cross-operator comparison and filtering. Derived from bedrooms and structure. Consistency: layoutType = 'studio' implies bedrooms = 0.","enum":["studio","1-bed","2-bed","3-bed","4-bed","5-bed","duplex","penthouse","maisonette","loft","cluster_flat"]},"unitType":{"type":"string","description":"Operator-specific unit taxonomy. Not standardized or comparable across operators. Examples: operator codes or labels (e.g., '1B-Type-04', 'A1', 'FP-C'), not generic values like 'studio'."},"marketSegment":{"type":"string","description":"The market segment this Unit belongs to.","enum":["BTR","CoLiving","Student","SFH"]},"status":{"type":"string","description":"Current availability status of this Unit. Availability is derived, not contractual. Lease/tenancy is never exposed.","enum":["available","reserved","let","unknown","offMarket"]},"lastVerifiedDate":{"type":"string","description":"Date when this Unit's information was last verified. Format: YYYY-MM-DD.","format":"date"},"isActive":{"type":"boolean","description":"Whether this Unit is currently active. false for retired/superseded units."},"supersedesUnitId":{"type":"array","description":"Array of Unit IDs that this Unit supersedes (for split/merge history). Empty array if none.","items":{"type":"string"},"default":[]},"supersededByUnitId":{"type":"array","description":"Array of Unit IDs that supersede this Unit (for split/merge history). Empty array if none.","items":{"type":"string"},"default":[]},"availableFrom":{"type":"string","description":"Date from which this Unit is available. Format: YYYY-MM-DD.","format":"date"},"idUrl":{"type":"string","description":"Immutable, ID-based identity URL for this entity. Uses the Unit ID token in the path (eg /property/{token}), never the handle, and never includes a country prefix. Stable, immutable, deterministic.","format":"uri"},"dataUrl":{"type":"string","description":"Direct JSON endpoint on the Property Service open data domain. Format: https://{env}.property.rentiful.ai/data/v1/{entityTypePlural}/{entityId}. Same domain family as schemas and OpenAPI.","format":"uri"},"handle":{"type":"string","description":"Optional human-readable handle for this entity. A mutable alias, not part of identity. Identity remains the canonical unitId.","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":2,"maxLength":64},"canonicalUrl":{"type":"string","description":"Canonical Rentiful URL (SEO canonical). Format: https://rentiful.ai/{cc}/property/{idToken}. Uses the Unit ID token in the path (never handle). Uses countryCode if available, otherwise equals idUrl. Mutable, may change if countryCode changes.","format":"uri"}},"required":["unitId","buildingId","placeId","operatorId","status","lastVerifiedDate","isActive"],"additionalProperties":false,"x-generated-at":"2026-04-07T09:04:12.735Z","x-contract":{"entity":"Unit","version":"v1"}},"Listing":{"title":"Listing","description":"Rentiful Open Data v1 contract schema for Listing. This is a public contract derived from the current data model, not a complete internal domain dump.","type":"object","properties":{"listingId":{"type":"string","description":"Canonical public identifier for this Listing. Opaque, human-friendly key.","pattern":"^l_[a-z2-7]{10}$","examples":["l_K7YZJWT2PQ"]},"unitId":{"type":"string","description":"The Unit this Listing is for. A Listing always belongs to a Unit.","pattern":"^u_[a-z2-7]{10}$"},"operatorId":{"type":"string","description":"The current managing brand for this Listing.","pattern":"^o_[a-z2-7]{10}$"},"status":{"type":"string","description":"Current availability status of this Listing.","enum":["available","reserved","let","unknown","offMarket"]},"rentPcm":{"type":"string","description":"Monthly rent in pence (GBP) or smallest currency unit.","minimum":0},"currency":{"type":"string","description":"ISO 4217 currency code for rent amounts.","pattern":"^[A-Z]{3}$","examples":["GBP","USD","EUR"]},"availableFrom":{"type":"string","description":"Date from which this Listing is available. Format: YYYY-MM-DD.","format":"date"},"minTenancyMonths":{"type":"string","description":"Minimum tenancy length in months.","minimum":1},"maxTenancyMonths":{"type":"string","description":"Maximum tenancy length in months, if applicable.","minimum":1},"depositWeeks":{"type":"string","description":"Deposit amount expressed as weeks of rent.","minimum":0},"petsAllowed":{"type":"string","description":"Whether pets are allowed in this Listing."},"furnished":{"type":"string","description":"Furnishing status of this Listing.","enum":["furnished","unfurnished","partFurnished"]},"firstPublishedAt":{"type":"string","description":"When this Listing was first published. Format: ISO 8601 date-time.","format":"date-time"},"lastUpdatedAt":{"type":"string","description":"When this Listing was last updated. Format: ISO 8601 date-time.","format":"date-time"},"canonicalUrl":{"type":"string","description":"Canonical Rentiful URL (SEO canonical). Format: https://rentiful.ai/property/{idToken}. Uses the Unit ID token (since listings are transient views of units). Mutable, may change if the unit's countryCode changes.","format":"uri"},"idUrl":{"type":"string","description":"Immutable, ID-based identity URL for this entity. Uses the Listing ID token in the path.","format":"uri"},"dataUrl":{"type":"string","description":"Direct JSON endpoint on the Property Service open data domain.","format":"uri"}},"required":["listingId","unitId","operatorId","status"],"additionalProperties":false,"x-generated-at":"2026-04-07T09:04:12.735Z","x-contract":{"entity":"Listing","version":"v1"}},"Operator":{"title":"Operator","description":"Rentiful Open Data v1 contract schema for Operator. This is a public contract derived from the current data model, not a complete internal domain dump.","type":"object","properties":{"operatorId":{"type":"string","description":"Canonical public identifier for this Operator. Opaque, human-friendly key.","pattern":"^o_[a-z2-7]{10}$","examples":["o_M2GTB2LZJZ"]},"name":{"type":"string","description":"The name of this Operator (e.g., 'Get Living', 'Quintain Living', 'Vertus').","minLength":1},"idUrl":{"type":"string","description":"Immutable, ID-based identity URL for this entity. Uses the Operator ID token in the path (eg /operators/{token}), never the handle, and never includes a country prefix. Stable, immutable, deterministic.","format":"uri"},"dataUrl":{"type":"string","description":"Direct JSON endpoint on the Property Service open data domain. Format: https://{env}.property.rentiful.ai/data/v1/{entityTypePlural}/{entityId}. Same domain family as schemas and OpenAPI.","format":"uri"},"handle":{"type":"string","description":"Optional human-readable handle for this entity. A mutable alias, not part of identity. Identity remains the canonical operatorId.","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":2,"maxLength":64},"canonicalUrl":{"type":"string","description":"Canonical Rentiful URL (SEO canonical). Format: https://rentiful.ai/operators/{handle}. Requires handle. No country prefix for operators. Mutable, may change if handle changes. May be omitted if handle is not available.","format":"uri"},"url":{"type":"string","description":"Public URL for this Operator, if available.","format":"uri"}},"required":["operatorId","name"],"additionalProperties":false,"x-generated-at":"2026-04-07T09:04:12.735Z","x-contract":{"entity":"Operator","version":"v1"}}}}}