Create a property
Adds a property to a portfolio. Units are created separately afterwards, so a new property starts with no units and every rollup at zero.
Authorization
AuthorizationstringrequiredBody
application/json
namestringWhat to call the property, 1 to 150 characters. Leave it out and displayName falls back to the street address.
addressobjectrequiredWhere the property is. Required, even though its parts are only lightly validated.
typeenum<string>requiredWhat kind of building this is. singleFamily and condo — and townHome once it has exactly one unit — make the property a single-unit one, which changes how MagicDoor renders addresses and returns defaultUnit.
portfolioIdstringrequiredThe portfolio to put the property in.
imageSessionIdstringId of a completed upload session for the property's main photo. The file is claimed and becomes imageId.
imageIdstringdeprecatedId of an already-uploaded but unclaimed file. Use imageSessionId instead.
magicTagsobjectFree-form labels, as a map of string keys to string values.
totalFloorsintegerNumber of floors in the building, 1 to 200.
Response
200 · The new property, hydrated. `customFieldValues` is absent here — this endpoint does not load custom field values.
idstringSnowflake id of the property.
namestringThe name a property manager gave the property. Absent when the property was never named.
displayNamestringWhat to show in a list: the name if there is one, otherwise streetAddress1, otherwise the literal "Unnamed Property". Computed on every read.
addressobjectThe property's address. Absent when no address has been recorded.
portfolioIdstringThe portfolio this property sits in.
typeenum<string>What kind of building this is. A singleFamily or condo property, and a townHome with exactly one unit, is treated as a single-unit property elsewhere in the API.
totalFloorsintegerNumber of floors in the building, 1 to 200. Absent when it was never set.
unitCountintegerHow many units belong to the property, active and deactivated together. Maintained by MagicDoor as units are created and deleted; you cannot set it.
recentRentalApplicationsintegerHow many rental applications naming this property arrived in the recent window. Computed; you cannot set it.
activebooleanfalse once the property has been deactivated.
imageIdstringThe file behind the property's main photo. Absent when no photo has been set.
iconsstring[]Icon keys pinned to the property. Free-form strings.
magicTagsobjectFree-form labels on the property, as a map of string keys to string values. MagicDoor stores them as given and uses them to scope things like vendor bills. Absent when none are set.
imageobjectThe property's main photo, resolved from imageId. Absent when no photo has been set.
portfolioobjectThe portfolio this property sits in, expanded.
totalRentnumberComputed: the sum of currentRent across the property's active leases. Not stored — you cannot set it.
currentBalancenumberComputed: the sum of balance across the property's active leases. A positive figure means tenants owe money.
postedBalancenumberComputed: the sum of postedBalance across the property's active leases — the same total as currentBalance but counting only charges that have already been posted.
totalDepositnumberComputed: the sum of securityDepositPaid across the property's active leases.
occupiedUnitsintegerComputed: how many distinct units of this property have an active lease.
activeUnitsintegerComputed: how many of the property's units are active. Differs from unitCount, which also counts deactivated units.
emptyUnitsintegerComputed as activeUnits minus occupiedUnits.
ownersobject[]Who owns the property and in what share. Empty when no owner has been linked.
defaultUnitobjectThe property's only unit, returned when the property is a single-unit one — singleFamily, condo, or a townHome with exactly one unit. Absent otherwise.
400 · A required field is missing or fails validation — no address, an unknown property type, a name over 150 characters, or `totalFloors` outside 1 to 200. The response carries an `errors` member mapping each rejected field name to its message.
401 · The access token is missing, expired, or not for this company.
404 · No portfolio with that id.
MagicDoor nests records four deep: a portfolio holds properties, a property holds units, and a lease is signed on a unit. Every property names exactly one portfolioId; move it with the move endpoint rather than by writing that field. A property is the building — the rent, the tenants and the money all hang off its units.
Creating a singleFamily or condo property also creates one unit on it, named Home, because for those the building is the rentable thing. Every other type — including townHome — starts with no units, and you add them through the units endpoints.
Start an upload with Start a property photo upload first, send the bytes, then pass that session's id as imageSessionId here. Doing it in one call saves you a follow-up update.