Architectural requests

Create an architectural request

Files a new architectural request on behalf of an owner. It starts in draft, so the board does not see it until that owner submits it from the owner portal. Requires the hoa_architectural_requests:write permission.

POST

https://services.magicdoor.com/hoa/company-portal/associations/architectural-requests

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

propertyIdstringrequired

The property the requested work is on.

example: 1830472847398402048

submittedByOwnerIdstringrequired

The owner the request is filed for. Required here even though it is optional in the owner portal, and it is the owner who will be able to submit the draft.

example: 1830472847398405120

titlestringrequired

Short summary of the work. Trimmed before it is stored.

descriptionstringrequired

Full description of the work. Trimmed before it is stored.

unitIdstring

The unit the work is on. Omit it when the request covers the whole property.

portfolioIdstring

The portfolio to file the request under.

dueAtstring · date-time

Deadline for the board to finish voting. Send an ISO 8601 timestamp with an offset, for example 2026-09-13T09:12:44-04:00. Omit it and the deadline is set 30 days out.

filesobject[]

Files to attach immediately. Each one must already exist — upload new files with the upload session endpoint instead.

Response

200 · The new request, in `draft`.

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 · `submittedByOwnerId` is missing or is not a number, `title` or `description` is blank, 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.

`submittedByOwnerId` is required here

The field is optional in the request body, but this endpoint rejects a request without it. It also has to parse as a number — a name or an email gets 400 Bad Request.

The response never carries propertyName, unitName, or submittedByOwnerName: those are resolved only when you read the request back.

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.