Leases

Create a lease

Creates a lease on a unit with its rent and any other recurring charges. Set draft to true to hold it as a draft you activate later, or false to make it live straight away.

POST

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

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

unitIdstringrequired

The unit to put the lease on. A Snowflake id, sent as a decimal string.

startstring · daterequired

First day of the lease term.

endstring · date

Last day of the fixed term. Required unless monthToMonth is true.

monthToMonthbooleanrequired

Whether the lease continues month to month after the fixed term.

tenantIdsstring[]required

Tenants to put on the lease.

rentobjectrequired

The recurring rent charge.

otherChargesobject[]

Further recurring charges, such as parking or pet rent. Same shape as rent.

proratedAmountnumber

A one-off prorated rent charge for the partial first period. Use the prorated-amount endpoint to work it out.

depositnumber

Security deposit to request.

draftbooleanrequired

true to create the lease as a draft, false to make it live immediately.

fromTypeenum<string>

What the lease was created from, when it came from another record.

rentalApplication

fromEntityIdstring

Id of that record. A Snowflake id, sent as a decimal string.

Response

200 · The lease that was created.

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.

400 · The body failed validation — for example an end date is missing on a lease that is not month-to-month, or a recurring charge starts before the lease does.