MagicDoorAPI
SupportOpen MagicDoor
Letter document templates

Start a document file upload

Asks for a one-time upload slot for a Word document you want to use as a letter document template, or to put in place of the current one.

POST
https://services.magicdoor.com/communications/company-portal/letter-templates/documents/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.

Body

application/json

Describe the file you are about to upload. Only Word .docx files are accepted, up to 20 MB — anything else is refused when you commit.

fileNamestringrequired

The file's name, 1 to 250 characters. Its extension should be .docx.

fileSizeintegerrequired

The exact size of the file in bytes. Must be at least 1 and no more than 20971520 (20 MB).

contentTypestringrequired

The file's media type, 1 to 200 characters. Only application/vnd.openxmlformats-officedocument.wordprocessingml.document is accepted.

Response

200 · Where to send the file, and what to send with it.

sessionIdstringrequired

Identifies the upload once it has finished. This is the value you send back as uploadSessionId.

endpointstringrequired

The storage URL to send the file to. It is not a MagicDoor host and it does not take your bearer token.

methodstringrequired

The HTTP method to use against endpoint.

fieldsobjectrequired

Form fields that must be sent with the file, exactly as given, before the file part. The set varies by upload, so send back whatever comes down rather than a fixed list.

expiresstring · date-timerequired

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

400 · `fileName`, `fileSize` or `contentType` is missing or outside its allowed range.

401 · The access token is missing, expired, or not a property-manager token.

422 · The file service refused the session — most often because the media type is not .docx or the size is over 20 MB.

The three steps

  1. Ask for a session

    Call this endpoint with the file's name, size and media type. You get back a storage URL, an HTTP method, and a set of form fields.

  2. Upload the file to storage

    Send a multipart form to endpoint using method. Put every entry of fields in the form first, then the file itself as the last part. Do not send your MagicDoor bearer token to that URL — the signed fields are the authorisation.

  3. Hand the session back to MagicDoor

    Send the sessionId from step 1 to Create a letter document template as uploadSessionId, or to Replace a template's file to put it over an existing template. A session is good for one of those, once.

This session is not interchangeable with the one from Start a template file upload. Each is minted against its own storage reference, and passing one where the other is expected fails with a 422.