MagicDoorAPI
SupportOpen MagicDoor
Architectural requests

Create a file upload session

Asks for a short-lived presigned upload target for a file you want to attach to a draft architectural request. Requires the hoa_architectural_requests:write permission.

POST
https://services.magicdoor.com/hoa/company-portal/associations/architectural-requests/{boardRequestId}/files/upload-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

boardRequestIdstringrequired

The architectural request to act on.

example: 1830472847398404096

Body

application/json

fileNamestringrequired

Name to store the file under. Between 1 and 250 characters.

fileSizeintegerrequired

Exact size of the file in bytes. At least 1 and at most 20971520 (20 MB).

contentTypestringrequired

MIME type of the file, between 1 and 200 characters. Images, video, audio, PDF, Word and Excel documents, plain text, JSON, XML, ZIP, and 7z are accepted.

Response

200 · Where to upload the file, and until when.

sessionIdstring

Pass this to the add-files endpoint once the upload has finished.

endpointstring

The presigned URL to upload the bytes to.

methodstring

The HTTP method to use against endpoint, for example PUT or POST.

fieldsobject

Extra form fields the storage provider requires. Send them with the upload; empty for a plain PUT.

expiresstring · date-time

When the presigned target stops working, in the company's timezone.

400 · The request is not in `draft`, the file is larger than 20 MB, the content type is not allowed, `fileName`/`contentType` is empty or too long, `fileSize` is below 1, 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.

Attaching a file

  1. Ask for an upload session

    Call this endpoint with the file's name, exact byte size, and MIME type. You get back a presigned endpoint and a sessionId.

  2. Upload the bytes

    Send the file to endpoint using the method returned, including every entry in fields as form data. This call does not go through the MagicDoor API.

  3. Attach it to the request

    Call Add files with the sessionId. Until you do, the file is not on the request and the session eventually expires.

Drafts only

This is legal only while the request is in draft. Once it has been submitted for board voting the request's files are fixed, and you get 400 Bad Request with the detail Files can only be uploaded to draft board requests.

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.