MagicDoorAPI
SupportOpen MagicDoor
Maintenance requests

Create a maintenance request

Files a maintenance request against a lease on behalf of a tenant. MagicDoor reads the description and writes the title, picks a category and scores the urgency, unless you set disableAi. The property, unit and portfolio are taken from the lease. Requires the maintenance_requests:write permission.

POST
https://services.magicdoor.com/maintenance/company-portal/maintenance-requests

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

There is no title here on purpose — MagicDoor writes one from the description. To attach photos, create the request first, then use Attach files to a maintenance request.

requesterIdstringrequired

The tenant the request is filed on behalf of.

leaseIdstringrequired

The lease the request is against. It must belong to the same company and must not have ended.

assignedPropertyManagerIdstring

The property manager to put in charge of the request.

descriptionstringrequired

What is wrong, in the requester's words. At least one character. MagicDoor writes the title from this.

internalDescriptionstring

Notes for staff only, never shown to the tenant.

statusenum<string>required

The state to file the request in. Normally pending.

closedpendinginProgressaiProcessingwaitingForWorkOrder
urgencyenum<string>

How urgent the request is. Omitting it files the request as urgent, because that is the first value of the list — send one explicitly.

default: urgenturgenthighmediumlownone
permissionToEnterboolean

Whether someone may enter the unit when the tenant is not home.

default: false
duestring · date

The date the work is wanted by.

disableAiboolean

true files the request without letting MagicDoor read it. The title then falls back to a placeholder and the urgency score stays at 0.

default: false
categoryIdstring

The maintenance request category to file it under. MagicDoor overrides this if it picks a category of its own while reading the request.

filesobject[]deprecated

Attach files at creation time by naming committed upload sessions. Use the files endpoint instead.

Response

200 · The maintenance request that was filed.

idstringrequired

The maintenance request.

assignedPropertyManagerIdstring

The property manager who owns this request. Absent while nobody is assigned.

unitIdstringrequired

The unit the request is about.

propertyIdstringrequired

The property the request is about.

portfolioIdstringrequired

The portfolio the property sits in.

leaseIdstringrequired

The lease the request was filed against.

tenantIdstringrequired

The tenant who is recorded as the requester.

chatIdstring

The chat carrying the conversation about this request. Absent until a chat is opened — see Open the chat on a maintenance request.

titlestringrequired

A short summary of the problem. MagicDoor writes it from the description when the request is created; you cannot set it on create, only change it later.

statusenum<string>required

Where the request has got to. waitingForWorkOrder means it has been triaged but the job has not been scheduled yet; aiProcessing means MagicDoor is still reading it.

closedpendinginProgressaiProcessingwaitingForWorkOrder
urgencyenum<string>required

How urgent the request is. Set by staff, or by MagicDoor when it reads the request.

urgenthighmediumlownone
categoryIdstring

The maintenance request category the request is filed under. Absent when it has not been categorised.

disableAibooleanrequired

Whether MagicDoor has been told to leave this request alone.

aiUrgencyScoreintegerrequired

How urgent MagicDoor judged the request to be when it read it. 0 when it has not been read.

createdstring · date-timerequired

When the request was filed, in the company's timezone and without an offset.

lastUpdatedstring · date-timerequired

When the request last changed, in the company's timezone and without an offset.

aiProcessedbooleanrequired

Whether MagicDoor has finished reading the request.

newRequestbooleanrequired

Whether the request was filed recently enough to count as new. The window is a company setting, so the same request stops being new without anything changing on it.

locationobject

Where the request is, looked up from the property and unit at read time. Individual properties are absent when the property or unit could not be read.

descriptionstringrequired

What the requester reported, in their words.

internalDescriptionstring

Notes for staff only, never shown to the tenant. Absent when there are none.

filesobject[]required

Photos, videos and PDFs attached to the request. An empty array when there are none.

permissionToEnterbooleanrequired

Whether the tenant agreed that someone may enter the unit when they are not home.

duestring · date

The date the work is wanted by, in the company's timezone. Absent when no date was set.

runBookIdstring

The runbook currently handling the request. Absent when no runbook picked it up.

workOrderIdstring

The work order created from this request. Absent until one is created.

400 · The description is empty, or the lease does not exist or belongs to another company.

401 · The request carried no valid access token.

403 · The token is not a property manager token, or it lacks the `maintenance_requests:write` permission.

404 · `categoryId` names a category that does not exist, or belongs to another company.

422 · The lease has ended, so nothing can be filed against it.