MagicDoorAPI
SupportOpen MagicDoor
Unit listings

Start a listing custom field file upload

Starts an upload for a file that will become the value of a file-type custom field on this listing. Returns where to send the bytes; nothing is attached until you set the field's value with the session id.

POST
https://api.portal.magicdoor.com/company-app/unit-listings/{unitId}/custom-fields/{customFieldId}/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
customFieldIdstringrequired

Snowflake id of the custom field definition, from the list-custom-fields response on this listing.

example: 1830472847398404099

Body

application/json

Describe the file you are about to upload. MagicDoor checks it against the rules for that custom field 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 referenceFileUploadSessionId when you set the field's value.

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 the custom field does not accept, or a size outside its limits.

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

404 · No listing or no custom field with that id, or one of them 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 listing custom field on the same listing and custom field, passing this session's id as referenceFileUploadSessionId, or as one entry of referenceFileUploadSessionIds when the field holds several files.