Client Portfolios

Advisors and higher admin roles manage portfolios of Individual and Business Owner clients — both types support full listing, filtering, detail view, account inspection, and balance export.

Client Types

Individual Client Management

List Individual Clients

GET /branches/private/v1/individual

• Auth: Advisor (or higher) access token

GET /branches/private/v1/individual?page[number]=1&page[size]=20&filter[status]=active
Authorization: Bearer <advisor_token>

Query parameters:

Response fields per client:

Invite an Individual Client

POST /branches/private/v1/individual

• Auth: Advisor access token

{
  "firstName": "Jane",
  "lastName": "Doe",
  "phoneNumber": "+12025550101",
  "email": "[email protected]"
}

An invitation email is sent to the client immediately.

Get Individual Client Details

GET /branches/private/v1/individual/:id

• Auth: Advisor (or higher) access token

Returns the full client profile including KYC status, personal details, and assigned Advisor.

Import Individual Clients in Bulk

POST /branches/private/v1/branch/import-individuals

• Auth: Root Advisor or Head Branch Manager access token
• Body: multipart/form-data with a CSV file

Contact [email protected] for the CSV template format.

Individual Client Accounts (Admin View)

Advisors can inspect the accounts belonging to any client in their portfolio using the accounts service endpoints. The response is scoped to the calling user's role — an Advisor only sees clients in their portfolio; a Root Advisor sees all clients.

List Accounts for a Client

GET /accounts/private/v1/account

• Auth: Advisor (or higher) access token

Filter by user to see a specific client's accounts:

GET /accounts/private/v1/account?filter[userId]=<client-user-id>
Authorization: Bearer <advisor_token>

Get Account Details

GET /accounts/private/v1/account/:id

• Auth: Advisor (or higher) access token

Returns account details including:

Get Account Bank Details

GET /accounts/private/v1/account/:id/bank-details

• Auth: Advisor (or higher) access token

Returns routing number, IBAN, SWIFT code, and account number for the account.

Export Individual Account Balances

GET /accounts/private/v1/account/export/individual-balances

• Auth: Advisor (or higher) access token
• Response: XLSX file download (Excel-compatible)
• Filename: individual-balances.xlsx

Downloads a spreadsheet of all Individual clients in scope with their current account balances. Scope is determined by role: an Advisor gets their own portfolio; a Root Advisor gets the full organization.

GET /accounts/private/v1/account/export/individual-balances
Authorization: Bearer <advisor_token>
Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Business Owner Client Management

List Business Owner Clients

GET /branches/private/v1/businessowner

• Auth: Advisor (or higher) access token

GET /branches/private/v1/businessowner?page[number]=1&page[size]=20&filter[status]=active
Authorization: Bearer <advisor_token>

Response fields per business client:

Invite a Business Owner Client

POST /branches/private/v1/businessowner

• Auth: Advisor access token

{
  "businessName": "Acme Corp",
  "firstName": "John",
  "lastName": "Smith",
  "phoneNumber": "+12025550102",
  "email": "[email protected]",
  "advisorID": "<advisor-id>"
}

Get Business Owner Client Details

GET /branches/private/v1/businessowner/:id

• Auth: Advisor (or higher) access token

Returns the full business profile including:

• Business information (legal name, EIN, registration date, legal structure, state of incorporation, industry code, website)
• Business Owner personal information (name, date of birth, SSN, address)
• KYB status and any rejection errors

Assign a Business Owner to a Different Advisor

PATCH /branches/private/v1/businessowner/assign

• Auth: Head Branch Manager access token

{
  "businessOwnerId": "<client-id>",
  "advisorId": "<new-advisor-id>"
}

Import Business Owners in Bulk

POST /branches/private/v1/branch/import-business-owners

• Auth: Root Advisor or Head Branch Manager access token
• Body: multipart/form-data with a CSV file

Business Owner Accounts (Admin View)

Advisors can view business accounts using the same account endpoints, scoped to the business owner's user ID:

GET /accounts/private/v1/account?filter[userId]=<business-owner-user-id>
Authorization: Bearer <advisor_token>

External accounts (bank accounts linked via Plaid) are on a separate endpoint:

GET /external-accounts/private/v1/account

GET /external-accounts/private/v1/account?filter[userId]=<business-owner-user-id>
Authorization: Bearer <advisor_token>

GET /external-accounts/private/v1/account/:id — get a specific linked external account.

Client Status Lifecycle

Both Individual and Business Owner clients move through this lifecycle from invitation to active account.

flowchart LR
    Invited --> Onboarding --> Pending["Pending KYC/KYB\napproval"]
    Pending --> Active
    Active --> Dormant
    Dormant --> Closed
    Pending --> Rejected

Portfolio Scope by Role