Accounts

The accounts resource is your tenant's directory of brokerage accounts — every investor you have onboarded, addressable as a list and as individual records. An account is the same underlying record as an investor; "account" is the noun most integrations reach for, and the list shape (paginated, status-filtered, broker-attributed) is what a back office actually needs.

The account id is the investor_id. Anywhere an endpoint takes an investor_id (orders, balances, transfers), pass an account id unchanged.

Both endpoints are plain Bearer reads — no signature required.

The account object

Field	Type	Notes
id	string	inv_… — the account id (= investor id)
account_number	string	the account reference at the broker of record
status	string	active | restricted | closed
currency	string	EGP
name	string	account holder's full name
shariah_only	bool	investor-elected shariah screen
suitability	object	{ tier, recorded, risk_acknowledged }
broker	object	{ id, name, fra_license_no, contact_email, contact_phone }
created_at	timestamp	when the account was opened

status meanings:

• active — fully operational.
• restricted — may divest existing holdings but cannot open new positions.
• closed — read-only.

suitability.tier is 0 none · 1 conservative · 2 balanced · 3 growth. recorded is true once the suitability questionnaire is on file; risk_acknowledged once the investor has accepted the risk disclosure. Both are gates that must be satisfied before equity trading (see Onboarding).

GET /v1/accounts

List the accounts under the authenticated tenant, newest first.

Query	Notes
status	filter by standing: active | restricted | closed
limit	page size, 1–200 (default 100)

curl "https://sandbox.boursa.sh/v1/accounts?status=active&limit=50" \
  -H "Authorization: Bearer $BOURSA_API_KEY"

{
  "accounts": [
    {
      "id": "inv_8sKq…",
      "account_number": "ACME-000123",
      "status": "active",
      "currency": "EGP",
      "name": "Mona Saleh",
      "shariah_only": false,
      "suitability": { "tier": 2, "recorded": true, "risk_acknowledged": true },
      "broker": {
        "id": "brk_egx_01",
        "name": "Sandbox Partner Brokerage",
        "fra_license_no": "FRA-SBX-0001",
        "contact_email": "desk@brokerage.eg",
        "contact_phone": "+20…"
      },
      "created_at": "2026-06-01T09:12:44+03:00"
    }
  ]
}

Accounts are scoped to your tenant — the list never includes another tenant's accounts.

GET /v1/accounts/{id}

A single account by id. Returns the same object as above (not wrapped in an array). 404 NOT_FOUND if the id is unknown or belongs to another tenant.

curl https://sandbox.boursa.sh/v1/accounts/inv_8sKq… \
  -H "Authorization: Bearer $BOURSA_API_KEY"

Related

• Investors — the per-account identity profile plus its sub-resources (balances, activities, suitability).
• Onboarding — how an account comes into existence (KYC → broker approval).
• Portfolio & positions — holdings and analytics for an account.