Request a connected account
Asks MagicDoor to board one of the company's bank accounts with the payment processor, so money can settle to it. The signer's details and the date they accepted are recorded as the agreement acceptance, and MagicDoor signs and stores an agreement document from them. Requires the connected_accounts:write permission.
Authorization
AuthorizationstringrequiredBody
application/json
The bank account to board, the business information behind it, and who signed for it.
bankAccountIdstringrequiredThe company bank account to settle to, held in the Accounting service. It must belong to the calling company and carry a name, a nine-digit routing number that passes the ABA checksum, an account number of 4 to 17 digits, and a type of checking or savings. A Snowflake id, sent as a decimal string.
companyBusinessInfoIdstringrequiredThe company business information record submitted with the request. It must belong to the calling company. It does not have to be approved yet. A Snowflake id, sent as a decimal string.
documentsobject[]Supporting files, each one already uploaded through an upload session. Defaults to none.
signerNamestringrequiredThe name of the person accepting the agreement, 1 to 200 characters.
signerEmailstring · emailrequiredThe signer's email address.
signerPhonestringrequiredThe signer's phone number.
signerAddressobjectrequiredThe signer's home address.
signerSsnstringrequiredThe signer's US Social Security number, as XXX-XX-XXXX or as nine digits with no separators. The example below shows an all-zero placeholder rather than a usable number.
signerDateOfBirthstring · daterequiredThe signer's date of birth, as YYYY-MM-DD.
acceptedstring · daterequiredThe date the signer accepted the agreement, as YYYY-MM-DD. It is read in the company's timezone.
Response
200 · The connected account, newly created with `status` of `requested`, put back to `requested` if one was already there and still open, or returned unchanged if it had already moved on.
idstringrequiredThe connected account. Send this value wherever a connectedAccountId is asked for. A Snowflake id, sent as a decimal string.
companyIdstringrequiredThe company that owns the connected account. Always the calling company.
bankAccountIdstringrequiredThe company bank account, held in the Accounting service, that this connected account settles to.
statusenum<string>requiredWhere the account stands. requested means MagicDoor has the request and has not boarded it yet, pending that boarding started but nothing was submitted, underReview that the processor is reviewing it, approved that the processor said yes but the account is not live, activated that it can process payments, rejected and suspended that the processor turned it down or stopped it, exception that it needs attention, and denied that MagicDoor turned it down.
companyBusinessInfoIdstringrequiredThe company business information record submitted with the request.
documentsobject[]requiredThe files held against the account. The signed agreement acceptance is added by MagicDoor and is always among them; the rest are the ones sent with the request.
denyReasonstringWhy MagicDoor denied the request. Present only while status is denied.
400 · A field is missing or malformed — a signer SSN that does not match `XXX-XX-XXXX`, an invalid email or phone number, an address part outside its length, or two documents quoting the same upload session.
401 · The request carried no valid access token.
403 · The token is not a property manager token, or it lacks the `connected_accounts:write` permission.
404 · No such bank account or company business information record, or it belongs to another company, or the bank account was deleted.
422 · The bank account cannot be boarded — it has no name, its routing number is not nine digits or fails the ABA checksum, its account number is not 4 to 17 digits, or its type is neither checking nor savings. Also returned when a document's upload session could not be turned into a stored file.
One bank account has at most one connected account with the processor MagicDoor runs. If one already exists and it is still requested, or MagicDoor previously denied it, this call replaces the business information, the documents, and the agreement acceptance on it and puts it back to requested — the documents attached before are deleted. If it has moved past that, to pending, underReview, approved, activated, rejected, suspended, or exception, the call changes nothing and returns the account as it stands.
Upload each supporting file first with Start a connected account document upload, then list the session ids here. Every uploadSessionId in documents must be distinct. If any of them cannot be turned into a stored file the whole request fails with 422 and no connected account is written.