Leases

Get a lease

Fetches one lease with its unit, property and tenants filled in, including the derived status that tells you whether it is a draft, live, expired, in eviction, or ended.

GET

https://api.portal.magicdoor.com/company-app/leases/{leaseId}

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

leaseIdstringrequired

The lease to fetch. A Snowflake id, sent as a decimal string.

example: 1830472847398404096

Response

200 · The lease.

idstring

Id of the lease. A Snowflake id, sent as a decimal string.

portfolioIdstring

Portfolio the lease rolls up to. A Snowflake id, sent as a decimal string.

propertyIdstring

Property the lease's unit sits in. A Snowflake id, sent as a decimal string.

unitIdstring

Unit the lease is for. A Snowflake id, sent as a decimal string.

startstring · date

First day of the lease term.

endstring · date

Last day of the fixed term. Absent on an open-ended month-to-month lease.

endedboolean

Whether the lease has been ended. A lease whose end date has passed is expired, not ended; expiry never ends a lease by itself.

monthToMonthboolean

Whether the lease continues month to month once the fixed term runs out.

evictionboolean

Whether the lease is flagged as being in eviction.

chatIdstring

Chat thread for the lease. A Snowflake id, sent as a decimal string.

balancenumber

What the tenants owe right now, counting payments that have not settled yet. A decimal amount, not cents.

postedBalancenumber

What the tenants owe counting only settled money.

currentRentnumber

Current recurring rent, as a decimal amount.

securityDepositPaidnumber

How much security deposit has been paid.

securityDepositRequestednumber

How much security deposit was asked for.

securityDepositDuenumber

securityDepositRequested minus securityDepositPaid.

lastPaymentDatestring · date

Date of the most recent payment. Absent when nothing has been paid.

earliestUnpaidBillDueDatestring · date

Due date of the oldest charge still owing. Absent when nothing is owed.

pastDueDaysinteger

Days since earliestUnpaidBillDueDate. Absent unless the balance is positive and that date is in the past.

iconsstring[]

Icon keys the portal shows against the lease.

moveOutDatestring · date

Agreed move-out date, when one has been set.

draftboolean

Whether the lease is still a draft and has not been activated.

statusenum<string>

The lease's state, worked out from the flags and dates above. draft before activation; future when the start date has not arrived; lease during a fixed term; leaseMonthToMonth during a fixed term that rolls over afterwards; monthToMonth once it has rolled over or when there is no end date; expired when a fixed term ended and does not roll over, in which case the lease is still live and still accrues charges; eviction while the eviction flag is set; ended once the lease has actually been ended.

leaseleaseMonthToMonthmonthToMonthevictionexpireddraftendedfuture

expiringStatusenum<string>

How close the end date is: immediate within two weeks, imminent within a month, soon within two months, otherwise none. Always none for draft, ended, month-to-month, and open-ended leases.

nonesoonimminentimmediate

tenantsHydratedLeaseTenant[]

Tenants on the lease, each with the full tenant record.

unitobject

The unit the lease is for.

propertyobject

The property the lease's unit sits in.

customFieldValuesCustomFieldValue[]

Values of the company's custom fields for this lease. Absent when the endpoint does not load them.

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

404 · No lease matched the id, or it belongs to another company.

Lease states

A lease is a draft until it is activated, future before its start date, and a live lease after that. When a fixed term runs past its end date the lease becomes expired, which in MagicDoor is a normal ongoing state — rent keeps being charged and nothing about the lease is cancelled. Expiry never turns into ending. A lease only becomes ended when someone ends it, and eviction is a separate flag that can be set while the lease is live.