MagicDoorAPI
SupportOpen MagicDoor
External insurance

Create an external insurance record

Records a policy the tenant bought from an insurer outside MagicDoor, on their behalf. The record is created awaiting review and does not cover the lease until it is approved. Requires the leasing_insurance:write permission.

POST
https://services.magicdoor.com/tenantinsurance/company-portal/insurance/externals

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

To attach the tenant's policy document, first create an upload session, upload the file to the address it returns, then send that session's id here as uploadSessionId.

leaseIdstringrequired

The lease the policy covers. It must belong to the calling company.

carrierNamestringrequired

The insurance company that issued the policy. Up to 250 characters.

policyNumberstringrequired

The policy number from the document. Up to 250 characters.

coverageAmountnumberrequired

Coverage in dollars. Must be greater than 0.

policyStartDatestring · date-timerequired

When the policy takes effect. Must be earlier than policyEndDate.

policyEndDatestring · date-timerequired

When the policy expires. Must be in the future.

stateenum<string>

Accepted by the request but not applied: the record is always created awaiting review. Use the approve endpoint to approve it.

pendingapprovedrejected
fileIdstringdeprecated

The id of a file already uploaded to the Files service. Use uploadSessionId instead.

uploadSessionIdstring

The id of the upload session the policy document was uploaded through. The document is attached to the record and kept.

Response

200 · The record that was created. Its `state` is `pending`.

idstring

The external insurance record's id.

leaseIdstring

The lease this policy covers.

companyIdstring

The company that owns the lease.

carrierNamestring

The insurance company that issued the policy. An empty string when none was recorded.

policyNumberstring

The policy number taken from the document. Absent when none was recorded.

coverageAmountnumber

Coverage in dollars. Absent when none was recorded.

policyStartDatestring · date-time

When the policy takes effect.

policyEndDatestring · date-time

When the policy expires.

stateenum<string>

Where the record stands with the reviewer. A new record starts at pending; only an approved record counts as coverage for the lease.

pendingapprovedrejected
rejectionReasonstring

Why the record was rejected. Absent unless state is rejected and a reason was given.

insurancePolicyFileobject

The uploaded proof of insurance. Absent when the record has no document attached.

deletedstring · date-time

When the record was deleted. Absent while the record is live.

createdstring · date-time

When the record was created.

updatedstring · date-time

When the record last changed.

400 · A field failed validation: the coverage amount is not above 0, the start date is not before the end date, the end date is in the past, or a required field is missing.

401 · The access token is missing, expired, or not a company portal token.

403 · The token is valid but the caller does not hold the `leasing_insurance:write` permission.

404 · No such lease, or the lease belongs to another company.