MagicDoorAPI
SupportOpen MagicDoor
Vendors

Create a vendor

Adds a vendor and creates the portal account they sign in with. The response is the only place the account's password is ever returned — nothing else exposes it, so capture it or send a portal invite later. Requires the vendors:write permission.

POST
https://services.magicdoor.com/maintenance/company-portal/vendors

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

typeenum<string>

What kind of party this is. Omitting it files them as hoa, because that is the first value of the list — send other for an ordinary trade vendor.

default: hoahoapropertyManagerother
namestringrequired

The vendor's business name. Between 1 and 200 characters.

languagestringrequired

The ISO 639-1 language code to write to the vendor in, for example en.

memostring

A free-text note about the vendor. Send it out entirely rather than sending an empty string.

websitestring

The vendor's website. Send it out entirely rather than sending an empty string.

categoryIdstring

The vendor category to file them under. The category must exist.

contactobject

How to reach the vendor.

addressobject

The vendor's postal address. Note this sits beside contact, not inside it, on the way in — the response nests it under contact.

insurancePolicyobject

The vendor's liability insurance.

iconsstring[]

Labels to pin to the vendor. They are stored lower-case.

defaultMemostring

Text to pre-fill onto bills raised for this vendor.

paymentSettingsobject

How the vendor is paid.

irs1099Formobject

Tax details for issuing a 1099.

clearTextPasswordstring

The password to give the vendor's portal account. Between 5 and 150 characters. Leave it out and one is generated; either way the password comes back in the response.

Response

200 · The vendor that was created. This response carries `password`; no other endpoint does.

idstringrequired

The vendor.

companyIdstringrequired

The company that owns the vendor record.

typeenum<string>required

What kind of party this is. hoa is a homeowners association, propertyManager is a management company, other is an ordinary trade vendor.

hoapropertyManagerother
namestringrequired

The vendor's business name.

languagestringrequired

The ISO 639-1 language code MagicDoor writes to the vendor in, for example en.

memostring

A free-text note about the vendor. Absent when there is none.

activebooleanrequired

Whether the vendor can be assigned work and sign in. false after they have been deactivated.

websitestring

The vendor's website. Absent when none was recorded.

categoryIdstring

The vendor category the vendor is filed under. Absent when uncategorised.

contactobjectrequired

How to reach the vendor. The object is always present; the values inside it may be absent.

insurancePolicyobject

The vendor's liability insurance. Absent when none was recorded.

irs1099Formobject

Tax details used when the vendor is issued a 1099. Absent when none were recorded.

chatIdstring

The chat MagicDoor uses to talk to this vendor. Absent until one is opened.

disableChatbooleanrequired

Whether chat with this vendor is switched off.

iconsstring[]required

Lower-case labels pinned to the vendor, used to flag them in lists. An empty array when there are none.

isCompanyVendorbooleanrequired

true when this record stands for the management company itself rather than an outside vendor. Such a record cannot be deleted or deactivated.

defaultMemostring

Text pre-filled onto bills raised for this vendor. Absent when none was set.

paymentSettingsobjectrequired

How the vendor is paid.

lastSeenstring · date-time

When the vendor last used their portal, in the company's timezone and without an offset. Absent when they never have.

lastPortalInvitestring · date-time

When a portal invite was last sent, in the company's timezone and without an offset. Absent when none has been sent.

portalStatusenum<string>required

Worked out from the two timestamps above: active once the vendor has signed in, invited once an invite has gone out, notInvited before that.

notInvitedinvitedactive
createdstring · date-timerequired

When the vendor record was created, in the company's timezone and without an offset.

updatedstring · date-timerequired

When it was last changed, in the company's timezone and without an offset.

passwordstring

Only ever present on the response to creating a vendor — the sign-in password for their portal account. It is not stored in readable form and no other endpoint returns it.

400 · The name is empty or too long, the language is not a valid ISO 639-1 code, or the phone number could not be understood.

401 · The request carried no valid access token.

403 · The token is not a property manager token, or it lacks the `vendors:write` permission.

404 · `categoryId` names a vendor category that does not exist.

409 · The phone number or email address is already used by somebody else in the company. The response says which of the two, and what it clashed with.