MagicDoorAPI
SupportOpen MagicDoor
Unit listings

Start a listing image upload

Starts an upload for one listing image and returns where to send the bytes. The image is not part of the gallery until you add it with the session id.

POST
https://api.portal.magicdoor.com/company-app/unit-listings/{unitId}/images/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. A unit listing has no id of its own — it is keyed by the unit it markets, so this is also the listing's id.

example: 1830472847398404098

Body

application/json

Describe the file you are about to upload. MagicDoor checks it against the rules for a listing image 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 add the image.

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 listing image.

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

404 · No listing for that unit, 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 Add images to a listing on the same listing with this session's id as uploadSessionId, along with the caption, cover flag and position you want.