Architectural requests

Approve an architectural request

Records the manager's decision to approve an architectural request, closes any open board vote, and emails the submitting owner. Requires the hoa_architectural_requests:write permission.

POST

https://services.magicdoor.com/hoa/company-portal/associations/architectural-requests/{boardRequestId}/approve

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

boardRequestIdstringrequired

The architectural request to act on.

example: 1830472847398404096

Body

application/json

A body is required, but every field in it is optional — send {} to approve without a note.

notestring

Reason for the decision. It is stored on the request as pmNote and included in the email sent to the submitting owner.

Response

200 · The request, now `approved`.

idstring

The architectural request. A 64-bit id sent as a decimal string.

companyIdstring

The company the request belongs to.

portfolioIdstring

The portfolio the request was filed under. Absent when it was created without one.

propertyIdstring

The property the requested work is on.

propertyNamestring

Never returned by this endpoint — only the list and the single-request read resolve property names.

unitIdstring

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

unitNamestring

Never returned by this endpoint — only the list and the single-request read resolve unit names.

submittedByOwnerIdstring

The owner the request was filed on behalf of.

submittedByOwnerNamestring

Never returned by this endpoint — only the single-request read resolves owner names.

titlestring

Short summary of the work being requested.

descriptionstring

Full description of the work being requested.

statusenum<string>

Where the request has reached in the review workflow.

draftboardVotingreadyForPmReviewapproveddeniedcancelled

dueAtstring · date-time

Deadline for the board to finish voting, in the company's timezone. Defaults to 30 days after creation, and is absent once it has been cleared.

isOverdueboolean

true once the deadline passed while the request was still in boardVoting and a background sweep moved it to readyForPmReview. It is never set back to false.

voteSessionIdstring

The board vote opened for this request. Absent until the request has been submitted for voting.

boardRequestProgressobject

Never returned by this endpoint — only the single-request read computes voting tallies.

pmDecisionenum<string>

The manager's final decision. Absent until the request is approved or denied.

approveddenied

pmDecidedAtstring · date-time

When that decision was recorded, in the company's timezone. Absent until it is made.

pmNotestring

The note the manager left with the decision. Absent when none was sent.

filesobject[]

Files attached to the request. Empty when there are none.

createdstring · date-time

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

updatedstring · date-time

When the request last changed, in the company's timezone.

400 · The request is not in `boardVoting` or `readyForPmReview`, or the calling company is not in HOA business mode.

401 · The bearer token is missing, expired, or not valid.

403 · The token is valid but the caller does not hold the `hoa_architectural_requests:write` permission.

404 · No request with that id belongs to the calling company.

Legal from `boardVoting` and `readyForPmReview`

Calling this on a request that is draft, approved, denied, or cancelled returns 400 Bad Request with the detail Board request is not ready for Hoa Manager decision. Read the request first if you are not sure what state it is in.

A manager can approve while the board is still voting — the open vote is closed as part of the same call, and the tallies are left as they were. The submitting owner gets an email naming the decision and the note.

HOA companies only

Every architectural request and board member endpoint first checks that the calling company is set up as an HOA. A company in any other business mode gets 400 Bad Request with the detail Company is not in HOA business mode.