MagicDoorAPI
SupportOpen MagicDoor
Resident benefit packages

Enroll a tenant in a benefit package

Enrolls one tenant on a lease into one of the company's packages, on the property manager's behalf. Requires the resident_benefit_packages:write permission.

POST
https://services.magicdoor.com/productexperiences/company-portal/resident-benefit-packages/leases/{leaseId}/enrollments

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

leaseIdstringrequired

The lease the tenant is on, as a Snowflake id in decimal string form.

example: 1839884127209783296

Body

application/json

tenantIdstringrequired

The tenant to enroll, as a Snowflake id in decimal string form. They must be on the lease and not moved out.

packageIdstringrequired

The package to enroll them in, as a Snowflake id in decimal string form. It must belong to this company and be enabled.

Response

200 · The new enrollment, `pendingActivation`, with `enrolledBy` `propertyManager` and `enrolledVia` `company_portal`.

idstringrequired

The enrollment, as a Snowflake id in decimal string form.

leaseIdstringrequired

The lease the enrolled tenant is on.

unitIdstringrequired

The unit that lease is for.

propertyIdstringrequired

The property that unit belongs to.

tenantIdstringrequired

The enrolled tenant.

packageIdstringrequired

The package the tenant is enrolled in.

statusenum<string>required

pendingActivation is enrolled but not yet live with the partner, active is live, cancelled is terminal — re-enrolling creates a new record.

pendingActivationactivecancelled
enrolledAtstring · date-timerequired

When the enrollment was created, in the company's timezone.

enrolledByenum<string>required

Who performed the enrollment. Always propertyManager for an enrollment made through this API.

tenantpropertyManagersystem
enrolledViastringrequired

The surface the enrollment came from. Enrollments made through this API are stamped company_portal.

commitmentMonthsintegerrequired

The commitment the tenant took on, copied from the package at enrollment and fixed afterwards.

committedUntilstring · date-timerequired

The end of the tenant's commitment, in the company's timezone. It is the floor for a tenant-requested cancellation, not for a property manager's.

serviceStartsAtstring · date-timerequired

When benefits and billing begin. Enrolling on or after the 15th of a month pushes this to the start of the next month; enrolling before a lease starts anchors it to the lease start.

retailPriceSnapshotnumberrequired

The package's list price at the moment of enrollment, as a decimal amount.

customRetailPricenumber

A per-tenant price the property manager set on this enrollment. Absent when there is none; 0 means the property manager funds it.

effectiveRetailPricenumberrequired

What this enrollment bills next: the per-tenant override if one is set, otherwise the price snapshot while the price lock holds, otherwise the package's current list price.

cancellationRequestedAtstring · date-time

When the tenant asked to cancel. Absent when no request is outstanding.

cancelAtstring · date-time

When a scheduled cancellation takes effect. Absent when nothing is scheduled. No charge is posted for a period starting on or after it.

cancelOriginenum<string>

Who scheduled the pending cancellation. Absent when nothing is scheduled.

tenantpropertyManagersystem
cancelledAtstring · date-time

When the enrollment actually reached cancelled. Absent until then.

cancelledByenum<string>

Who cancelled it. Absent until it is cancelled.

tenantpropertyManagersystem
cancelledReasonstring

The reason recorded with the cancellation. Absent until it is cancelled.

firstChargedAtstring · date-time

When the first charge posted. Absent until then.

paidThroughstring · date-time

Exclusive end of the latest month a charge actually posted for. Absent until the first charge. It is what paid-through cancellation maths is based on.

nextChargeDatestring · date-time

When the next monthly charge is due. Absent once the enrollment is cancelled.

400 · The program is switched off for this company, the lease has ended, the tenant has moved out, the tenant has no email address on file, or the package is not enabled.

401 · The request carried no valid access token.

403 · The caller is not a property manager, or is missing the `resident_benefit_packages:write` permission.

404 · The lease is not this company's, the tenant is not on the lease, or the package is not this company's.

409 · The package cannot be combined with one the tenant already holds.

When benefits start

The enrollment is created as pendingActivation. serviceStartsAt is worked out from the later of today and the lease start, in the company's timezone: on a day before the 15th it is that day, and on the 15th or later it moves to the start of the next month. The enrollment goes active once the first charge has posted and the service month has arrived.

commitmentMonths is copied from the package and fixed for good, and committedUntil is that many calendar months out.

Upgrades and conflicts

A tenant can hold several packages at once as long as they do not share an exclusivity group. Within one group, enrolling into a higher tier than the one they hold is an upgrade — the old enrollment is cancelled automatically with the reason Upgraded, the longer of the two commitments is kept, and the billing already paid for carries across. Enrolling into a lower tier, or into a package that clashes with one they hold, is refused with 409.