MagicDoorAPI
SupportOpen MagicDoor
Work orders

Book a visit on a work order

Books a slot for someone to attend. A work order can carry several, and they are what the schedule board draws. A visit added after the first one must not be earlier than the first. Requires the work_orders:write permission.

POST
https://services.magicdoor.com/maintenance/company-portal/work-orders/{workOrderId}/sessions

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

workOrderIdstringrequired

The work order to act on. A Snowflake id, sent as a decimal string.

example: 1841200938471029248

Body

application/json

scheduledTimestring · date-timerequired

When the visit starts. Send it with a UTC offset, for example 2026-08-19T16:00:00+00:00; the response gives it back in the company's timezone.

durationMinutesinteger

How long to book, in minutes. Must be at least 1. Leave it out for 60.

default: 60

Response

200 · The work order, with the new visit in `sessions`.

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 · `durationMinutes` is zero or less, or the visit is earlier than the work order's first booked visit.

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 · No such work order, or it belongs to another company.