Recurring work orders

Create a recurring work order

Sets up a schedule that raises a work order on a repeating pattern. Creating one immediately raises the occurrences that fall inside the company's look-ahead window, so work orders can exist the moment this call returns. Requires the work_orders:write permission.

POST

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

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 one of propertyId, unitId or leaseId; MagicDoor fills in the rest of the location from it.

descriptionstringrequired

What the recurring job is. Between 1 and 2000 characters. MagicDoor writes the title from it when you leave title out.

urgencyenum<string>required

The urgency each generated work order gets.

urgenthighmediumlownone

frequencyenum<string>required

How often the job repeats, before interval is applied.

dailyweeklymonthlyyearly

startsFromstring · daterequired

The earliest date an occurrence may fall on. MagicDoor moves it forward to the first date the pattern allows, and the response tells you where it landed.

propertyIdstring

The property the work is on. Give either this, unitId or leaseId — whichever you give, the rest of the location is worked out from it.

unitIdstring

The unit the work is on.

leaseIdstring

The lease the work is tied to.

vendorIdstring

The vendor each generated work order goes to. It must be one of the company's vendors and must still be active.

assignedPropertyManagerIdstring

The property manager to put on each generated work order. They must belong to the company and must still be active.

titlestring

The title each generated work order gets. At most 250 characters. Leave it out and MagicDoor writes one from the description.

internalDescriptionstring

Notes for staff only. At most 2000 characters.

permissionToEnterboolean

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

default: true

intervalinteger

How many periods sit between occurrences. Between 1 and 99. 2 with weekly means every other week.

default: 1

weekdaysenum<string>[]

Which days of the week an occurrence falls on. Only allowed when frequency is weekly — sending it with any other frequency is rejected.

sundaymondaytuesdaywednesdaythursdayfridaysaturday

workSessionTemplatesobject[]

The visits to book into each occurrence. Leave it out and the generated work order carries a due date but no booked visit.

endsOnstring · date

The date the schedule stops. It cannot be earlier than startsFrom. Leave it out to run forever.

Response

200 · The schedule that was created, with `startsFrom` and `nextDueDate` set to the first date the pattern allows.

idstringrequired

The recurring work order.

portfolioIdstringrequired

The portfolio the property sits in. Worked out from the property, not sent by you.

propertyIdstringrequired

The property the work is on.

unitIdstring

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

leaseIdstring

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

vendorobject

The vendor the generated work orders go to, in the same shape as Get a vendor. Absent when no vendor is set.

locationobject

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

assignedPropertyManagerIdstring

The property manager put on each generated work order. Absent when nobody is assigned.

titlestring

The title each generated work order gets. MagicDoor writes one from the description when you do not supply it.

descriptionstringrequired

What the recurring job is.

internalDescriptionstring

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

urgencyenum<string>required

The urgency each generated work order gets.

urgenthighmediumlownone

permissionToEnterbooleanrequired

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

frequencyenum<string>required

How often the job repeats, before interval is applied.

dailyweeklymonthlyyearly

intervalintegerrequired

How many of those periods sit between occurrences. 2 with weekly means every other week.

weekdaysenum<string>[]required

Which days of the week an occurrence falls on. Only used by a weekly schedule; an empty array otherwise.

sundaymondaytuesdaywednesdaythursdayfridaysaturday

workSessionTemplatesobject[]required

The visits booked into each occurrence. An empty array means the generated work order carries a due date but no booked visit.

startsFromstring · daterequired

The date the first occurrence falls on. MagicDoor moves the date you sent forward to the first date the pattern actually allows, so this can differ from what you sent.

endsOnstring · date

The date the schedule stops. Absent when it runs forever.

nextDueDatestring · daterequired

The date of the next occurrence still to be raised.

lastCreatedOnstring · date-time

When a work order was last raised from this schedule, in the company's timezone and without an offset. Absent when none has been.

activebooleanrequired

Whether the schedule is still raising work orders.

createdstring · date-timerequired

When the schedule was set up, in the company's timezone and without an offset.

400 · The description is empty or over 2000 characters, the title is over 250, `interval` is outside 1 to 99, `weekdays` was sent with a non-weekly frequency, a work session template has a duration of zero or less, or `endsOn` is earlier than `startsFrom`.

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.