Work orders

Create a work order

Raises a work order directly, without a maintenance request behind it. To raise one from a request instead, use Convert a maintenance request into a work order. Requires the work_orders:write permission.

POST

https://services.magicdoor.com/maintenance/company-portal/work-orders

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

Say where the work is with at least one of propertyId, unitId or leaseId; MagicDoor fills in the rest of the location from it.

descriptionstringrequired

What needs doing. Between 1 and 2000 characters. MagicDoor writes the title from it when you leave title out.

urgencyenum<string>required

How urgent the job is.

urgenthighmediumlownone

permissionToEnterbooleanrequired

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

propertyIdstring

The property the work is on.

unitIdstring

The unit the work is on.

leaseIdstring

The lease the work is tied to.

vendorIdstring

The vendor to give the job to. They must belong to the company and be active. Setting one stamps assignedOn.

maintenanceRequestIdstring

The maintenance request this job answers, when you are linking one by hand. Note that unlike the convert endpoint, this does not move the request's status or copy its files.

associationViolationIdstring

The association violation this job answers, when there is one.

assignedPropertyManagerIdstring

The property manager to put in charge. They must belong to the company and be active.

titlestring

What the job is, in a line. At most 150 characters. Leave it out and MagicDoor writes one from the description.

internalDescriptionstring

Notes for staff only. At most 2000 characters.

dueDatestring · date

The date the job is wanted by.

statusenum<string>

The state to raise it in. Leave it out for pending.

default: pendingclosedpendinginProgresscompletedcancelled

Response

200 · The work order that was raised.

idstringrequired

The work order.

referencestringrequired

The work order number people quote, generated when the work order is raised.

titlestringrequired

What the job is, in a line. MagicDoor writes it from the description when you do not supply one.

statusenum<string>required

Where the job has got to.

closedpendinginProgresscompletedcancelled

urgencyenum<string>required

How urgent the job is.

urgenthighmediumlownone

portfolioIdstringrequired

The portfolio the property sits in.

propertyIdstringrequired

The property the work is on.

unitIdstring

The unit the work is on. Absent when the job covers the whole property.

leaseIdstring

The lease the work is tied to. Absent when it is not tied to one.

vendorobject

The vendor doing the work, in the same shape as Get a vendor. Absent when no vendor is assigned. The properties below are the ones you are most likely to want; the full vendor record is returned.

locationobject

Where the work is, looked up from the property and unit at read time.

assignedOnstring · date-time

When a vendor was last put on the job, in the company's timezone and without an offset. Absent while no vendor is assigned.

chatIdstring

The chat with the vendor. Absent until one is opened — see Open the vendor chat on a work order.

groupChatIdstring

The chat with the vendor and the tenants together. Absent until one is opened.

assignedPropertyManagerIdstring

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

maintenanceRequestIdstring

The maintenance request this job came from. Absent when the job was raised on its own.

recurringWorkOrderIdstring

The recurring work order that raised this one. Absent when it was not raised on a schedule.

dueDatestring · date

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

sessionsobject[]required

The visits booked for this work order, earliest first. An empty array when nothing is booked.

createdstring · date-timerequired

When the work order was raised, in the company's timezone and without an offset.

updatedstring · date-time

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

descriptionstringrequired

What needs doing, in full.

internalDescriptionstring

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

permissionToEnterbooleanrequired

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

filesobject[]required

Files attached to the work order. An empty array when there are none.

billsobject[]

The work order's bills — its draft bills, plus the real vendor bills any of them have been converted into. An empty array when there are none.

chartOfAccountsobject[]required

The company's whole chart of accounts, included so a bill's account can be picked without a second call.

400 · None of `propertyId`, `unitId` or `leaseId` was sent; or the description is empty or over 2000 characters, the title is over 150, or the internal description is over 2000.

401 · The request carried no valid access token.

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

404 · The property, unit or lease could not be found for this company, or `vendorId` or `assignedPropertyManagerId` names somebody who does not exist for it.

422 · The vendor or the property manager has been deactivated.

Sending the same job twice

When maintenanceRequestId is set, MagicDoor looks for a live work order raised in the last five minutes against the same request and vendor with the same title and description. If it finds one, that existing work order is returned and nothing new is raised — so a retried call does not leave you with two jobs.