Work orders

Convert a maintenance request into a work order

Turns a reported problem into a scheduled job. The new work order takes the request's title, lease and entry permission, gets a description MagicDoor writes for the vendor, and receives copies of the request's files. The request itself is then moved to waitingForWorkOrder. Note the URL sits under maintenance requests, not work orders. Requires the maintenance_requests:write permission — not work_orders:write.

POST

https://services.magicdoor.com/maintenance/company-portal/maintenance-requests/{maintenanceRequestId}/convert-to-work-order

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

maintenanceRequestIdstringrequired

The maintenance request to convert. A Snowflake id, sent as a decimal string.

example: 1841003948572119040

Body

application/json

Every value here is optional; send {} to convert on the request's own terms.

vendorIdstring

The vendor to give the job to. They must belong to the company and be active. Leave it out to raise the work order unassigned.

dueDatestring · date

The date the job is wanted by. The request's own due date is not carried over, so set it here if you want one.

urgencyenum<string>

The urgency for the work order. Leave it out to take the request's urgency.

urgenthighmediumlownone

statusenum<string>

The state to raise the work order in. Leave it out for pending.

closedpendinginProgresscompletedcancelled

Response

200 · The work order that was raised. The maintenance request is now `waitingForWorkOrder`, and `maintenanceRequestId` on the work order points back at it.

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.

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 · No such maintenance request, it belongs to another company, or `vendorId` names a vendor that does not exist for it.

422 · The vendor has been deactivated.

The files are copied, not moved

Each file on the maintenance request is cloned into a new file owned by the work order. The request keeps its own copies, and removing a file from one side leaves the other side alone.