MagicDoorAPI
SupportOpen MagicDoor
Units

Start a unit photo upload

Starts an upload for the unit's main photo and returns where to send the bytes. Nothing is attached to the unit until you call set-photo with the session id.

POST
https://api.portal.magicdoor.com/company-app/units/{unitId}/image/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

unitIdstringrequired

Snowflake id of the unit, as a decimal string.

example: 1830472847398404098

Body

application/json

Describe the file you are about to upload. MagicDoor checks it against the rules for a unit photo and hands back somewhere to POST the bytes to.

fileNamestringrequired

The file's name including its extension, 1 to 250 characters. MagicDoor uses the extension when it decides whether the file is allowed.

fileSizeintegerrequired

Size of the file in bytes. Must be at least 1.

contentTypestringrequired

MIME type of the file, 1 to 200 characters, for example "image/jpeg".

Response

200 · An upload session. Nothing has been attached yet.

sessionIdstring

Snowflake id of the session. Pass it back as uploadSessionId when you set the unit's photo.

endpointstring

The absolute URL to send the file to. It belongs to the storage provider, not to MagicDoor, so do not add the MagicDoor bearer token to that request.

methodstring

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

fieldsobject

Extra form fields the storage provider requires with the upload, as a map of field name to value. Send them alongside the file. It can be empty when the provider needs none.

expiresstring · date-time

When the session stops accepting the upload. A wall clock in the company's timezone, with no offset.

400 · `fileName`, `fileSize` or `contentType` is missing, blank, or outside its length limits, or `fileSize` is below 1. The response carries an `errors` member mapping each rejected field name to its message.

422 · The file storage service refused the session — usually a content type or size that is not allowed for a unit photo.

401 · The access token is missing, expired, or not for this company.

404 · No unit with that id, or it belongs to another company.

  1. Ask for a session

    Call this endpoint with the file's name, size and content type.

  2. Upload the bytes

    Send the file to the endpoint the response gives you, using its method, and include every entry of fields with it. That request goes to the storage provider, so it does not carry your MagicDoor token.

  3. Attach it

    Call Set a unit's photo on the same unit, passing this session's id as uploadSessionId. Or pass it as imageSessionId when creating or updating the unit.