Investor Accounts

📘
Integrating through Apex AscendOS?
The product guidance on this page applies to you. The endpoints, fields and statuses are Monark's; use the AscendOS equivalents listed in Building on Apex AscendOS.

Every transaction is placed for an investor or an account. Both are built from parties — a person or an entity — created once and reused for everything that follows.

Monark endpoints used

Method	Endpoint	Purpose
`POST`	`/primary/v2/person`	Create an individual party
`POST`	`/primary/v2/entity`	Create an entity party
`POST`	`/primary/v2/entity/{id}/individuals`	Add a controlling individual to an entity
`POST`	`/primary/v2/account`	Open an account owned by one or more parties
`GET`	`/primary/v2/account/{id}`	Read an account back
`PUT`	`/primary/v2/account/{id}/accreditation`	Record accreditation. See Accreditation
`GET`	`/primary/v1/investor/{id}`	Read a party as an investor record

Workflow

Create the party — a person, or an entity plus at least one controlling individual.
Open the account, naming its owners and its registration type.
Record accreditation on the account. This is what activates its owners for private offerings.
Reuse them. Parties and accounts are created once per investor, not per order.

Create a person

POST /primary/v2/person

{
  "firstName": "Sarah",
  "lastName": "Chen",
  "email": "[email protected]",
  "dateOfBirth": "1985-04-12",
  "isUSBased": true,
  "citizenship": "US",
  "taxId": "000000000",
  "phoneCountryCode": "1",
  "phoneNumber": "5555550123",
  "physicalAddress": {
    "street1": "100 Market Street",
    "city": "San Francisco",
    "state": "CA",
    "zipCode": "94105",
    "countryCode": "US"
  },
  "financialInstitutionId": "{financialInstitutionId}",
  "referenceId": "your-own-party-reference"
}

Expect 201. The returned id is the party id, and it is the identifier everything downstream keys on.

A mailingAddress can be sent alongside physicalAddress where they differ.

Create an entity

POST /primary/v2/entity

Then, before the entity's account can trade:

POST /primary/v2/entity/{entityId}/individuals

Important: An entity with no active controlling individuals is refused at order time. Add them when you create the entity, not when the first order fails. This is the single most common entity-onboarding mistake.

Open the account

POST /primary/v2/account

{
  "financialInstitutionId": "{financialInstitutionId}",
  "registrationType": "Individual",
  "externalAccountNumber": "IND-0001",
  "owners": [
    { "partyId": "{personId}", "type": "Person", "isPrimary": true }
  ]
}

Field	Notes
`registrationType`	How the account is registered. See Which registrations can invest
`registrationSubtype`	Where the registration type takes one
`externalAccountNumber`	Your account number. Returned on reads, and the simplest reconciliation key
`owners[].partyId`	A person or entity id
`owners[].type`	`Person` or `Entity`
`owners[].isPrimary`	Exactly one owner is primary

Which registrations can invest

Important: Joint accounts and retirement accounts cannot subscribe to a Pre-IPO SPV. An order for one is refused with "{type} investors are not supported for PreIPO SPV subscriptions."

Filter these accounts out of the private markets experience entirely. An investor who browses offerings, reads a PPM and chooses an amount, only to be told at submission that their account type was never eligible, has had a bad experience your platform could have prevented at the first screen.

Individual and entity registrations are supported.

Parties and investors are the same identity

A v2 party id is a v1 investor id. The same GUID addresses both:

GET /primary/v1/investor/{partyId}

This matters because the two generations of the API coexist. The v1 investor endpoints carry data the v2 party endpoints do not expose, and several read endpoints — the SPV list and detail among them — are scoped by investorId, which is this same id.

Which identity to send on an order

Situation	Send
The investor has one account	Either `investorId` or `accountId`
The investor has several accounts	`accountId`. Sending `investorId` is refused with "The investor has multiple accounts. Supply AccountId through the v2 endpoint."
You want to send your own account number	`investorId` and `externalAccountNumber`. The latter cannot be combined with `accountId`

Exactly one of investorId or accountId is accepted — sending both is refused.

Implementation notes

Send a referenceId on party creation. It is your own identifier and is echoed back on reads.
Create once. Parties and accounts persist. Creating a new person per order will produce duplicate investors and fail uniqueness checks on email and tax id.
Sandbox and production are separate. A party created in sandbox does not exist in production.
An account must be open. A closed account is refused at order time with "The account is closed."

Next steps

Record how the investor qualifies: Accreditation
Show them what they can invest in: Marketplace