MagicDoorAPI
SupportOpen MagicDoor
Application documents

Start a document upload

Opens an upload session for a document on this application and returns where and how to send the bytes. Uploading is a three-step flow: start the session here, PUT or POST the file to the returned endpoint, then commit it. Requires the rental_applications:write permission.

POST
https://services.magicdoor.com/leasing/company-portal/rental-applications/{applicationId}/files/session

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

applicationIdstringrequired

The rental application to work with. A Snowflake id, sent as a decimal string.

example: 1830472847398404096

Body

application/json

fileNamestringrequired

The file name to store, including its extension. Between 1 and 255 characters.

Response

200 · The upload session. Send the file to `endpoint` using `method`, including every entry in `fields` as form data, then commit the session.

idstring

The upload session. Pass this id to the commit call.

companyIdstring

The company the session belongs to.

categorystring

What the file is being stored for. Always rentalApplication for these uploads.

fileNamestring

The file name you asked for.

statusenum<string>

Where the session is. prepared on creation, uploaded once the bytes arrive, committed once the file is attached.

prepareduploadedcommitted
allowedTypesstring[]

MIME types this session accepts. Fixed for rental-application documents at image/jpeg, image/png and application/pdf.

minSizeinteger

Smallest accepted file size in bytes. 1 for rental-application documents.

maxSizeinteger

Largest accepted file size in bytes. 10485760 — 10 MB — for rental-application documents.

endpointstring

Absolute URL to send the file to. This is the storage provider, not the MagicDoor API, and the host differs between environments — always use the value returned here.

methodstring

HTTP method to use for the upload, for example "POST".

fieldsobject

Form fields the storage provider requires alongside the file. Send every one of them, unchanged.

expiresstring · date-time

When the session stops accepting an upload, in the company's timezone.

storageKeystring

The provider's object key for the upload.

referencestring

What the session is bound to, as rental-application:{applicationId}. It is checked again on commit.

createdstring · date-time

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

updatedstring · date-time

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

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

403 · The caller is authenticated but does not hold the `rental_applications:write` permission.

404 · No rental application with this id exists, or it belongs to another company. Both cases look identical so that ids cannot be probed across companies.

Allowed in every application status

This is not gated on the application's status — it works on a draft, on a submitted application, and on a retracted one. Only the applicant-facing portal locks an application once it is submitted.

The three steps

  1. Start the session

    Call this endpoint with the file name. Keep the id and the endpoint, method and fields it returns.

  2. Send the bytes

    Post the file to endpoint with method, including every entry in fields as form data and the file itself last. This request goes to the storage provider, not to MagicDoor, and does not carry your access token.

  3. Commit the session

    Call Attach an uploaded document with the session id to attach the file to the application.

The session expires

Send the bytes and commit before expires. A session that lapses cannot be reopened — start a new one.