Units

Create a unit

Adds a unit to a property. Optionally creates the unit's marketing listing at the same time.

POST

https://api.portal.magicdoor.com/company-app/units

Authorization

Authorizationstringrequired

Bearer token — Send your API token in the Authorization header as Bearer <token>. Requests without a valid token are rejected with 401 Unauthorized.

Body

application/json

namestringrequired

What to call the unit — usually its number or letter, 1 to 150 characters. For a single-unit property "Home" is the usual choice.

propertyIdstringrequired

The property to add the unit to. It must be active.

addressobject

An address of the unit's own, for the rare case where it differs from the property's. Leave it out and the unit uses the property address.

bedsnumber

Bedrooms. Zero or more, in steps of 0.5.

bathsnumber

Bathrooms. Zero or more, in steps of 0.5.

unitSizeSqftinteger

Floor area in square feet. Zero or more.

marketRentnumber

The rent the unit is expected to fetch, as a decimal with at most two places, for example 1850.00. Between 0 and 1,000,000,000,000.

floorinteger

Which floor the unit is on. Must be at least 1 and no higher than the property's totalFloors, or 200 when the property does not declare one.

createUnitListingboolean

Set it true and MagicDoor creates the unit's marketing listing alongside the unit.

imageSessionIdstring

Id of a completed upload session for the unit's main photo.

imageIdstringdeprecated

Id of an already-uploaded but unclaimed file. Use imageSessionId instead.

magicTagsobject

Free-form labels, as a map of string keys to string values.

Response

200 · The new unit, hydrated.

idstring

Snowflake id of the unit.

namestring

The unit's name — typically its number or letter, for example "2B". For a single-unit property this is often "Home".

addressobject

An address that overrides the property's, for a unit with its own street address. Absent when the unit uses the property address, which is the usual case.

bedsnumber

Bedrooms. Whole or half numbers only. Absent when it was never set.

bathsnumber

Bathrooms. Whole or half numbers only. Absent when it was never set.

unitSizeSqftinteger

Floor area in square feet. Absent when it was never set.

marketRentnumber

The rent this unit is expected to fetch, as a decimal amount such as 1850.00. This is an asking figure on the unit, not the rent on any lease. Absent when it was never set.

floorinteger

Which floor the unit is on, 1 to 200. Absent when it was never set.

propertyIdstring

The property this unit belongs to.

portfolioIdstring

The portfolio the unit's property belongs to. Kept in step with the property.

activeboolean

false once the unit has been deactivated.

imageIdstring

The file behind the unit's main photo. Absent when no photo has been set.

iconsstring[]

Icon keys pinned to the unit. Free-form strings.

magicTagsobject

Free-form labels on the unit, as a map of string keys to string values. Absent when none are set.

imageobject

The unit's main photo, resolved from imageId. Absent when no photo has been set.

propertyobject

The property this unit belongs to, expanded.

activeLeasesLease[]

The leases currently running on this unit, in the same shape the leases endpoints return. Usually zero or one; more than one appears when leases overlap. Empty for a vacant unit.

postedBalancenumber

Computed: what the unit's leases owe, counting only charges that have already been posted.

singleLineAddressstring

Computed one-line address for the unit: the unit's own address if it has one, otherwise the property's address with the unit name appended. The unit name is left off for a single-unit property. Absent when neither the unit nor the property has an address.

recentRentalApplicationsinteger

Computed: how many distinct rental applications that have not been retracted named this unit in the recent window.

latestRentalApplicationIdstring

The most recent rental application, not retracted, that named this unit. Absent when nobody has applied.

400 · A required field is missing or fails validation — no name, `beds` or `baths` not a multiple of 0.5, `marketRent` with more than two decimal places, or a `floor` above the property's `totalFloors`. 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 · The property does not exist or belongs to another company.

422 · The property has been deactivated, so units cannot be added to it.

Where a unit sits

MagicDoor nests records four deep: a portfolio holds properties, a property holds units, and a lease is signed on a unit. The unit is the rentable thing — an apartment, a house, a shop. A single-family house is still modelled as a property with one unit, usually named "Home". portfolioId on a unit is a copy of its property's and follows the property when it moves.

A unit is not its listing

The unit holds the facts of the physical space — beds, baths, square feet, floor, marketRent. The unit listing is the marketing record MagicDoor publishes to prospective tenants: title, description, photos, asking rent, availability date. They share an id but have separate lifecycles and separate endpoints, and changing one does not change the other.