Unit listings

Get a unit listing

Fetches one listing in full — copy, gallery, amenities, pet policy and terms — together with the unit, property and portfolio behind it, and the reasons it cannot be published if any.

GET

https://api.portal.magicdoor.com/company-app/unit-listings/{unitId}

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.

Path parameters

unitIdstringrequired

Snowflake id of the unit. A unit listing has no id of its own — it is keyed by the unit it markets, so this is also the listing's id.

example: 1830472847398404098

Response

200 · The listing in full.

idstring

The listing's id, which is the same Snowflake as unitId.

portfolioIdstring

The portfolio behind the unit.

propertyIdstring

The property behind the unit.

unitIdstring

The unit this listing markets. Equal to id.

statusenum<string>

Where the unit stands from a letting point of view. This is the listing's own status; it is not derived from whether a lease exists.

pendingavailablereservedleasedoccupiedunderMaintenancesoldother

rentalPricenumber

The asking rent, as a decimal amount. This is the listing's price, separate from the unit's marketRent. Absent when it was never set, and a listing cannot be published without it.

securityDepositnumber

The deposit asked for, as a decimal amount. Absent when it was never set.

availableFromstring · date

The first date a tenant could move in. Absent when it was never set.

leaseTermenum<string>

The lease length being offered. Absent when it was never set.

monthToMonthhalfYearoneYeartwoYearsthreeYearsother

titlestring

The listing headline. Absent when it was never set.

listedstring · date

The date the listing was published. Its absence is what tells you the listing is not live — there is no separate boolean in the response.

updatedstring · date-time

When the listing last changed, as a wall clock in the company's timezone with no offset.

pinnedboolean

Whether a property manager pinned this listing to the top of their own list.

primaryImageobject

The image marked default, or the first one if none is. Absent when the listing has no images.

primaryVideoobject

The video marked default, or the first one if none is. Absent when the listing has no videos.

propertyTypeenum<string>

Copied from the property, so a search can filter on it without a second call.

singleFamilymultiFamilycommercialcondotownHomeother

singleLineAddressstring

The unit's address as one line. Absent when neither the unit nor its property has an address.

recentRentalApplicationsinteger

How many rental applications named this unit in the recent window. Computed.

descriptionstring

The listing body copy, up to 2500 characters. Absent when it was never written, and a listing cannot be published without at least 10 characters here.

descriptionTranslationsobject[]

The description in other languages. Absent when none exist. This endpoint does not write them.

imagesobject[]

The listing gallery, in the order MagicDoor stores it. Absent when there are none.

videosobject[]

The listing's videos. Absent when there are none.

tagsstring[]

Free-form marketing tags. Absent when none were set.

petPolicyobject

What pets are allowed and on what terms. Absent when no policy was set.

amenitiesobject[]

What the unit offers. Absent when none were recorded.

locationAnalysisstring

MagicDoor's write-up of the neighbourhood. Generated, not written by the caller. Absent when none has been produced.

termsobject

Extra terms of the offer, as a map of string keys to string values. Absent when none were set.

unitobject

The unit this listing markets, expanded.

portfolioobject

The portfolio behind the unit, expanded.

propertyobject

The property behind the unit, expanded.

canNotBeListedReasonsobject

Why this listing cannot be published, as a map from field name to a sentence explaining the problem. Keys you may see are rentalPrice (missing or not above zero), description (missing or under 10 characters) and unitActive (the unit is deactivated). Absent entirely when the listing is publishable — that absence is the signal to look for, not an empty object.

401 · The access token is missing, expired, or not for this company.

404 · No listing for that unit, the unit belongs to another company, or the listing has been deactivated.

Listing versus unit

The unit holds the facts of the physical space — beds, baths, square feet, floor, marketRent. The unit listing is the public marketing record: title, description, photos, videos, amenities, pet policy, asking rentalPrice, availableFrom. They share an id but have separate lifecycles: editing one does not touch the other, and a unit can exist with no listing at all. listed is what decides whether the listing is published; active on the unit is a different flag entirely.

A listing is keyed by its unit

A unit listing has no id of its own: its id, its unitId and the {unitId} in the path are all the same Snowflake. So there is exactly one listing per unit, and you address it by the unit's id.