Sandbox Walkthrough

This walkthrough takes two clients from account creation to a settled model order in the sandbox. Values are illustrative, and IDs in angle brackets come from earlier responses.

1. Find the custodian

GET /primary/v1/financial-institution lists the Financial Institutions Monark has set up for you. Note the id of the custodian that holds these clients' accounts.

2. Create each client and account

POST /primary/v2/person

{
  "referenceId": "client-1001",
  "financialInstitutionId": "<custodian id>",
  "firstName": "Jane",
  "lastName": "Doe",
  "dateOfBirth": "1980-04-12",
  "email": "[email protected]",
  "phoneCountryCode": "1",
  "phoneNumber": "5555550123",
  "taxId": "<client SSN, ###-##-####>",
  "citizenship": "US",
  "isUSBased": true,
  "physicalAddress": {
    "street1": "100 Main St",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "countryCode": "US"
  }
}

POST /primary/v2/account

{
  "financialInstitutionId": "<custodian id>",
  "registrationType": "Individual",
  "externalAccountNumber": "CUST-000123",
  "owners": [{ "partyId": "<person id>", "type": "Person", "isPrimary": true }]
}

Every account needs a current accreditation before it can order. Set it with PUT /primary/v2/account/{id}/accreditation. Orders for an account with no accreditation, one more than 12 months old, or one set to NOT_APPLICABLE are refused with 403 and AccountAccreditationInvalid.

3. Choose a fund and share class

GET /primary/v1/omnibus/fund?includeDocuments=true, then GET /primary/v1/omnibus/share-class?omnibusFundId=<fund id>. Check the share class minimums and the fund's eligibility flags. Each fund lists its prospectus, fact card and other documents.

4. Check and complete order requirements

POST /primary/v1/omnibus/order-action/requirements/batch

{
  "omnibusFundId": "<fund id>",
  "omnibusShareClassId": "<share class id>",
  "side": "Buy",
  "orders": [{ "accountId": "<account 1 id>" }, { "accountId": "<account 2 id>" }]
}

The response lists each account's actions with a definitionId, type, responsibleParty and display text. Present each one, then record it with PUT /primary/v1/omnibus/order-action/requirements/{definitionId}/complete and a body of { "accountId": "<account id>" }. A 204 means it is recorded. Questionnaire actions are recorded by submitting the answers with POST /primary/v1/questionnaire-answer. Repeat the batch check until allSatisfied is true: adding an account with open actions to a model order is refused with 409 and RequiredOrderActionsIncomplete.

5. Submit the model order

A model order is submitted in three calls. First create it as a draft with POST /primary/v1/omnibus/model-order:

{
  "referenceId": "rebal-2026-09-18-fund-a-buy",
  "modelId": "growth-alts",
  "omnibusFundId": "<fund id>",
  "omnibusShareClassId": "<share class id>",
  "financialInstitutionId": "<custodian id>",
  "side": "Buy",
  "currency": "USD",
  "distributionElection": "Drip",
  "taxLotElection": "FIFO",
  "routeInstruction": "TransferAgent"
}

A 201 returns the model order's id, with a status of Draft. Add the client lines with POST /primary/v1/omnibus/model-order/investor-orders:

{
  "modelOrderId": "<model order id>",
  "orders": [
    { "referenceId": "rebal-2026-09-18-1001", "accountId": "<account 1 id>", "notionalAmount": 40000 },
    { "referenceId": "rebal-2026-09-18-1002", "accountId": "<account 2 id>", "notionalAmount": 60000 }
  ]
}

A 200 returns a receivedOrderCount of 2. A larger book can be added in several batches. Then submit the model order with POST /primary/v1/omnibus/model-order/complete:

{
  "modelOrderId": "<model order id>",
  "totalOrderCount": 2
}

A 202 returns a status of Processing. Monark checks every line again and creates the client orders, then sends OmnibusModelOrderCreated with a status of Received. If a line fails a check, the whole model order is Rejected and OmnibusModelOrderRejected is sent instead. A draft that isn't completed is cancelled overnight.

For a single client, use POST /primary/v1/omnibus/order. It is a single call that takes the same fund, share class, side and election fields at the top level with one accountId and amount. It has no financialInstitutionId or orders list, since the custodian comes from the account.

6. Follow it to settlement

As the order moves, your webhook receives OmnibusModelOrderAccepted, an OmnibusOrderFundingInstruction at Monark's cutoff, OmnibusModelOrderSent and finally OmnibusModelOrderSettled. Client lines don't send their own events. Confirm the result with GET /primary/v1/omnibus/model-order/{id}, each line with GET /primary/v1/omnibus/order/{id}, and holdings with GET /primary/v1/omnibus/positions?accountId=<account id>&includeLots=true.