Business info

Update a principal on the draft

Changes one person on the open draft. Only the fields you send are changed; the rest keep their stored values. Requires the business_info:write permission.

PATCH

https://services.magicdoor.com/companies/company-portal/business-info/{businessInfoId}/principals/{principalId}

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

businessInfoIdstringrequired

The business legal entity, as a Snowflake id in decimal string form.

example: 1842095537184571392

principalIdstringrequired

The principal to change, as a Snowflake id in decimal string form.

example: 1842095560375074816

Body

application/json

Every field is optional. A field you leave out keeps its stored value.

firstNamestring

Given name. Up to 100 characters.

lastNamestring

Family name. Up to 100 characters.

emailstring · email

Email address, up to 250 characters. A value containing the bullet character • is treated as the masked value read back from a previous response and is ignored, leaving the stored address untouched.

phonestring

Phone number, up to 50 characters, validated and reformatted for storage. A value containing the bullet character • is ignored, leaving the stored number untouched.

addressobject

The principal's home address.

ssnstring

US Social Security number, up to 20 characters, nine digits with or without dashes. A value containing the bullet character • is ignored, leaving the stored number untouched.

dateOfBirthstring · date

Date of birth, as a calendar date.

driverLicenseobject

The principal's driver licence.

typeenum<string>

What the person is to the business.

controlPersonbeneficialOwner

ownershipinteger

Percentage of the business the principal owns. Between 0 and 100.

Response

200 · The draft, with the principal updated.

businessInfoIdstringrequired

The business legal entity this draft belongs to, as a Snowflake id in decimal string form. Allocated when the draft is created, before anything is approved.

typeenum<string>required

What the draft is doing. initial is a brand new legal entity, update amends an approved one, supplement is a request MagicDoor opened for more information.

initialupdatesupplement

statusenum<string>required

Where the draft sits in review. Editable in draft, waitingForInformation and rejected; pendingReview is with MagicDoor; superseded is closed.

draftpendingReviewwaitingForInformationrejectedsuperseded

legalNamestring

Registered legal name of the business.

legalEntityTypeenum<string>

How the business is incorporated.

soleProprietorshipllcprivateCompanypublicCompanyUnlistedpublicCompanyListedcharitableOrganizationNotForProfitpartnership

einstring

The federal tax identifier, masked: four bullet characters followed by the last four digits, for example ••••4321. The full value is never returned here.

mccCodestring

Merchant category code. Four digits once the draft is ready for approval.

summarystring

Free-text description of what the business does.

businessAddressobject

Registered address of the business.

startDatestring · date

The date the business started trading.

principalsobject[]required

The people behind the business, with their personal identifiers masked.

documentsobject[]required

Files attached to the draft, one entry per file.

resolvedRequirementobject

The document checklist pinned to this draft when it was created. Absent when no checklist resolved.

statusReasonstring

The reason recorded on the most recent workflow change that set the current status — a rejection note, or a request for more information. Absent when that change carried no reason.

400 · A field failed its length or range check.

401 · The request carried no valid access token.

403 · The caller is not a property manager, or is missing the `business_info:write` permission.

404 · No principal with that id is on the draft.

422 · This legal entity has no open draft, the draft is not editable, or the email address or phone number is not valid.

Masked values are ignored on write

The tax identifier, email address, phone number, Social Security number and driver licence number come back masked with the bullet character •. If you send a value back that still contains a bullet, MagicDoor treats it as the mask rather than as new data and leaves the stored value unchanged. Send a real value, or leave the field out.